Compare commits
1 Commits
feat/daemo
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
cea15a118b |
93
.github/pull_request_template.md
vendored
93
.github/pull_request_template.md
vendored
@ -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>
|
||||
|
||||
186
.github/workflows/release.yml
vendored
186
.github/workflows/release.yml
vendored
@ -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' }}
|
||||
|
||||
238
.github/workflows/sync-release-to-oss.yml
vendored
Normal file
238
.github/workflows/sync-release-to-oss.yml
vendored
Normal 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"
|
||||
@ -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**
|
||||
|
||||
|
||||
0
.qwen/skills/memory-leak-debug/scripts/find-leaf-node.sh
Normal file → Executable file
0
.qwen/skills/memory-leak-debug/scripts/find-leaf-node.sh
Normal file → Executable file
30
AGENTS.md
30
AGENTS.md
@ -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
|
||||
|
||||
|
||||
@ -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 复杂度
|
||||
|
||||
@ -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
@ -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
|
||||
|
||||
|
||||
878
docs/design/telemetry-outbound-propagation-design.md
Normal file
878
docs/design/telemetry-outbound-propagation-design.md
Normal 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 收录
|
||||
96
docs/developers/daemon-client-adapters/tui.md
Normal file
96
docs/developers/daemon-client-adapters/tui.md
Normal 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.
|
||||
@ -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.
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -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',
|
||||
|
||||
@ -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.
|
||||
|
||||
154
docs/developers/tools/monitor.md
Normal file
154
docs/developers/tools/monitor.md
Normal 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.
|
||||
1752
docs/plans/2026-05-14-auto-compaction-threshold-redesign.md
Normal file
1752
docs/plans/2026-05-14-auto-compaction-threshold-redesign.md
Normal file
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -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.
|
||||
@ -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
|
||||
|
||||
@ -143,6 +143,8 @@ 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 | **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` |
|
||||
@ -150,7 +152,7 @@ Settings are organized into categories. Most settings should be placed within th
|
||||
| `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` |
|
||||
@ -708,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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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.
|
||||
@ -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).
|
||||
|
||||
120
docs/verification/abort-controller-refactor/README.md
Normal file
120
docs/verification/abort-controller-refactor/README.md
Normal 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.
|
||||
139
docs/verification/abort-controller-refactor/automated-results.md
Normal file
139
docs/verification/abort-controller-refactor/automated-results.md
Normal 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.
|
||||
@ -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);
|
||||
@ -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,
|
||||
23
docs/verification/abort-controller-refactor/scripts/02-lite.sh
Executable file
23
docs/verification/abort-controller-refactor/scripts/02-lite.sh
Executable 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"
|
||||
18
docs/verification/abort-controller-refactor/scripts/06-headless-sigint.sh
Executable file
18
docs/verification/abort-controller-refactor/scripts/06-headless-sigint.sh
Executable 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")"
|
||||
@ -0,0 +1,2 @@
|
||||
0.15.11
|
||||
EXIT=0
|
||||
10
docs/verification/abort-controller-refactor/test-summary.txt
Normal file
10
docs/verification/abort-controller-refactor/test-summary.txt
Normal 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)
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -214,7 +214,6 @@ describe('qwen serve — capabilities envelope', () => {
|
||||
'workspace_preflight',
|
||||
'session_context',
|
||||
'session_supported_commands',
|
||||
'session_tasks',
|
||||
'session_close',
|
||||
'session_metadata',
|
||||
'mcp_guardrails',
|
||||
|
||||
3620
package-lock.json
generated
3620
package-lock.json
generated
File diff suppressed because it is too large
Load Diff
@ -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)
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "@qwen-code/acp-bridge",
|
||||
"version": "0.17.0",
|
||||
"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.",
|
||||
"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,26 +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"
|
||||
},
|
||||
"./internal/testUtils": {
|
||||
"types": "./dist/internal/testUtils.d.ts",
|
||||
"import": "./dist/internal/testUtils.js"
|
||||
},
|
||||
"./package.json": "./package.json"
|
||||
},
|
||||
"scripts": {
|
||||
@ -82,9 +62,7 @@
|
||||
"typecheck": "tsc --noEmit"
|
||||
},
|
||||
"files": [
|
||||
"dist",
|
||||
"!dist/internal/testUtils.*",
|
||||
"!dist/**/*.test.*"
|
||||
"dist"
|
||||
],
|
||||
"dependencies": {
|
||||
"@agentclientprotocol/sdk": "^0.14.1",
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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 8-arg constructor's positional slot opt-outs to
|
||||
* still works).
|
||||
*
|
||||
* Regression guard: the constructor takes 8 positional args; the
|
||||
* 6th (`fileSystem`) is optional. A subtle re-ordering (or
|
||||
* dropping the arg from `bridge.ts`'s factory
|
||||
* `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
@ -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
|
||||
|
||||
@ -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>;
|
||||
}
|
||||
@ -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,23 +77,6 @@ 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 `createHttpAcpBridge`. Most fields are
|
||||
* tuning knobs with sensible defaults; `boundWorkspace` is the only
|
||||
@ -248,18 +216,6 @@ export interface BridgeOptions {
|
||||
toolName: string,
|
||||
enabled: boolean,
|
||||
) => Promise<void>;
|
||||
/**
|
||||
* #4282 fold-in 5 (Codex P2-1). Optional override for the basename
|
||||
* (or single relative path) of the workspace context file written
|
||||
* by `POST /workspace/init`. When omitted, falls back to
|
||||
* `getCurrentGeminiMdFilename()` — the process-global value, which
|
||||
* the daemon parent never updates because it doesn't go through
|
||||
* `loadCliConfig`. Production callers (`runQwenServe`) snapshot the
|
||||
* resolved filename from the workspace's merged settings at boot
|
||||
* and pass it here so init writes the same file the ACP child
|
||||
* reads. Bridge tests can pass any literal.
|
||||
*/
|
||||
contextFilename?: string;
|
||||
/**
|
||||
* #4175 Wave 5 PR 22b/2 — optional injection seam for daemon-host
|
||||
* status cells (env snapshot, daemon preflight). Production
|
||||
@ -283,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;
|
||||
}
|
||||
|
||||
@ -16,19 +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,
|
||||
ServeWorkspaceEnvStatus,
|
||||
ServeWorkspaceMcpToolsStatus,
|
||||
ServeWorkspaceMcpStatus,
|
||||
ServeWorkspacePreflightStatus,
|
||||
ServeWorkspaceProvidersStatus,
|
||||
ServeWorkspaceSkillsStatus,
|
||||
ServeWorkspaceToolsStatus,
|
||||
ServeSessionContextUsageStatus,
|
||||
} from './status.js';
|
||||
|
||||
export interface BridgeSpawnRequest {
|
||||
@ -86,8 +81,6 @@ export interface BridgeSessionSummary {
|
||||
sessionId: string;
|
||||
workspaceCwd: string;
|
||||
createdAt: string;
|
||||
updatedAt?: string;
|
||||
title?: string;
|
||||
displayName?: string;
|
||||
clientCount: number;
|
||||
hasActivePrompt: boolean;
|
||||
@ -100,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;
|
||||
}
|
||||
|
||||
/**
|
||||
@ -197,19 +171,9 @@ export interface HttpAcpBridge {
|
||||
*/
|
||||
subscribeEvents(
|
||||
sessionId: string,
|
||||
opts?: SubscribeOptions & {
|
||||
/** Yield a synthetic `session_snapshot` frame after replay completes. */
|
||||
snapshot?: boolean;
|
||||
},
|
||||
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.
|
||||
@ -289,23 +253,11 @@ export interface HttpAcpBridge {
|
||||
*/
|
||||
getWorkspaceMcpStatus(): Promise<ServeWorkspaceMcpStatus>;
|
||||
|
||||
/**
|
||||
* Read discovered MCP tools for one server from the live ACP registry.
|
||||
*/
|
||||
getWorkspaceMcpToolsStatus(
|
||||
serverName: string,
|
||||
): Promise<ServeWorkspaceMcpToolsStatus>;
|
||||
|
||||
/**
|
||||
* Read daemon-runtime skill status for the bound workspace.
|
||||
*/
|
||||
getWorkspaceSkillsStatus(): Promise<ServeWorkspaceSkillsStatus>;
|
||||
|
||||
/**
|
||||
* Read the live built-in tool registry for the bound workspace.
|
||||
*/
|
||||
getWorkspaceToolsStatus(): Promise<ServeWorkspaceToolsStatus>;
|
||||
|
||||
/**
|
||||
* Read daemon-runtime model-provider status for the bound workspace.
|
||||
*/
|
||||
@ -329,20 +281,11 @@ export interface HttpAcpBridge {
|
||||
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.
|
||||
@ -370,35 +313,6 @@ export interface HttpAcpBridge {
|
||||
persisted: boolean;
|
||||
}>;
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
generateSessionRecap(
|
||||
sessionId: string,
|
||||
context?: BridgeClientRequestContext,
|
||||
): Promise<{ sessionId: string; recap: string | null }>;
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
executeShellCommand(
|
||||
sessionId: string,
|
||||
command: string,
|
||||
signal?: AbortSignal,
|
||||
context?: BridgeClientRequestContext,
|
||||
): Promise<ShellCommandResult>;
|
||||
|
||||
/**
|
||||
* Add or remove a tool name from the workspace's `tools.disabled`
|
||||
* settings list and fan-out a `tool_toggled` event to every live
|
||||
@ -424,77 +338,14 @@ export interface HttpAcpBridge {
|
||||
action: 'created' | 'overwrote' | 'noop';
|
||||
}>;
|
||||
|
||||
/**
|
||||
* 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,
|
||||
): Promise<
|
||||
| {
|
||||
name: string;
|
||||
transport: string;
|
||||
replaced: boolean;
|
||||
shadowedSettings: boolean;
|
||||
toolCount: number;
|
||||
originatorClientId: string;
|
||||
}
|
||||
| { 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' }
|
||||
>;
|
||||
|
||||
/**
|
||||
* Restart a configured MCP server through the ACP child's
|
||||
* `McpClientManager` (pre-F2) or transport pool (F2 #4175 commit 5).
|
||||
* Pre-checks the live budget snapshot and returns a structured
|
||||
* "skipped" response (200 OK) for soft refusals.
|
||||
*
|
||||
* F2 commit 5: under pool mode, a single `serverName` may map to
|
||||
* multiple `PoolEntry` instances (different fingerprints from
|
||||
* per-session OAuth/env divergence). When `opts.entryIndex` is
|
||||
* undefined, the pool restarts ALL matching entries in parallel via
|
||||
* `Promise.allSettled` and returns the new `{entries: RestartResult[]}`
|
||||
* shape. When `opts.entryIndex` is set, only that entry restarts
|
||||
* (404 / not-found surfaces as `entries: []`). Pre-F2 daemons and
|
||||
* single-entry pool-mode responses keep the legacy
|
||||
* `{restarted, durationMs}` shape so SDK clients that pre-date the
|
||||
* `mcp_pool_restart` capability tag observe no diff.
|
||||
* `McpClientManager`. Pre-checks the live budget snapshot and
|
||||
* returns a structured "skipped" response (200 OK) for soft refusals.
|
||||
*/
|
||||
restartMcpServer(
|
||||
serverName: string,
|
||||
originatorClientId: string | undefined,
|
||||
opts?: { entryIndex?: number },
|
||||
): Promise<
|
||||
| { serverName: string; restarted: true; durationMs: number }
|
||||
| {
|
||||
@ -503,15 +354,6 @@ export interface HttpAcpBridge {
|
||||
skipped: true;
|
||||
reason: 'in_flight' | 'disabled' | 'budget_would_exceed';
|
||||
}
|
||||
| {
|
||||
serverName: string;
|
||||
entries: Array<{
|
||||
entryIndex: number;
|
||||
restarted: boolean;
|
||||
durationMs?: number;
|
||||
reason?: string;
|
||||
}>;
|
||||
}
|
||||
>;
|
||||
|
||||
/**
|
||||
@ -539,18 +381,6 @@ export interface HttpAcpBridge {
|
||||
/** 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.
|
||||
@ -560,9 +390,3 @@ export interface HttpAcpBridge {
|
||||
/** Close all live child processes; called on daemon shutdown. */
|
||||
shutdown(): Promise<void>;
|
||||
}
|
||||
|
||||
export interface ShellCommandResult {
|
||||
exitCode: number | null;
|
||||
output: string;
|
||||
aborted: boolean;
|
||||
}
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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';
|
||||
|
||||
@ -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`);
|
||||
}
|
||||
@ -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 { createHttpAcpBridge } from '../bridge.js';
|
||||
import type { BridgeOptions } from '../bridgeOptions.js';
|
||||
import type { HttpAcpBridge } 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: `createHttpAcpBridge` 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> = {}): HttpAcpBridge {
|
||||
return createHttpAcpBridge({
|
||||
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;
|
||||
}
|
||||
@ -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
@ -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');
|
||||
});
|
||||
});
|
||||
@ -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();
|
||||
});
|
||||
}
|
||||
@ -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,19 +33,8 @@ 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', () => {
|
||||
|
||||
@ -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];
|
||||
@ -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,14 +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',
|
||||
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 =
|
||||
@ -177,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). */
|
||||
@ -276,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 {
|
||||
@ -360,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;
|
||||
@ -416,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.
|
||||
*
|
||||
@ -711,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
|
||||
|
||||
@ -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) {
|
||||
|
||||
@ -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();
|
||||
|
||||
@ -19,8 +19,8 @@ function decryptAesEcb(ciphertext: Buffer, key: Buffer): Buffer {
|
||||
/**
|
||||
* Parse aes_key from CDNMedia into a raw 16-byte Buffer.
|
||||
* Two encodings exist:
|
||||
* - base64(raw 16 bytes) → images
|
||||
* - base64(hex string of 16 bytes) → file/voice/video
|
||||
* - base64(raw 16 bytes)
|
||||
* - base64(hex string of 16 bytes)
|
||||
*/
|
||||
export function parseAesKey(aesKeyBase64: string): Buffer {
|
||||
const decoded = Buffer.from(aesKeyBase64, 'base64');
|
||||
|
||||
@ -240,6 +240,45 @@ describe('validateImagePath', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('allows Windows paths inside the workspace directory', () => {
|
||||
const imagePath = 'D:\\WorkGroup\\QwenCode\\002\\hello.png';
|
||||
const workspaceDir = 'D:\\WorkGroup\\QwenCode\\002';
|
||||
mockRealpathSync.mockImplementation((p: string) => {
|
||||
if (p.includes('hello.png')) return imagePath;
|
||||
if (p.includes('QwenCode\\002')) return workspaceDir;
|
||||
return p;
|
||||
});
|
||||
|
||||
expect(validateImagePath(imagePath, [workspaceDir])).toBe(imagePath);
|
||||
});
|
||||
|
||||
it('rejects Windows paths in a sibling directory with the same prefix', () => {
|
||||
const imagePath = 'D:\\WorkGroup\\QwenCode\\0022\\hello.png';
|
||||
const workspaceDir = 'D:\\WorkGroup\\QwenCode\\002';
|
||||
mockRealpathSync.mockImplementation((p: string) => {
|
||||
if (p.includes('hello.png')) return imagePath;
|
||||
if (p.includes('QwenCode\\002')) return workspaceDir;
|
||||
return p;
|
||||
});
|
||||
|
||||
expect(() => validateImagePath(imagePath, [workspaceDir])).toThrow(
|
||||
'Image path outside allowed directories',
|
||||
);
|
||||
});
|
||||
|
||||
it('does not treat POSIX backslashes as directory separators', () => {
|
||||
const imagePath = '/home/user/project\\escape.png';
|
||||
mockRealpathSync.mockImplementation((p: string) => {
|
||||
if (p.includes('escape.png')) return imagePath;
|
||||
if (p === '/home/user/project') return '/home/user/project';
|
||||
return p;
|
||||
});
|
||||
|
||||
expect(() => validateImagePath(imagePath, workspaceDirs)).toThrow(
|
||||
'Image path outside allowed directories',
|
||||
);
|
||||
});
|
||||
|
||||
it('rejects image with magic bytes that do not match extension', () => {
|
||||
// readSync returns JPEG magic, but file extension is .png
|
||||
vi.mocked(fs.readSync).mockImplementation((_fd: number, buf: Buffer) => {
|
||||
@ -325,8 +364,13 @@ describe('sendImage', () => {
|
||||
expectedEncrypted,
|
||||
);
|
||||
|
||||
// Step 4: send message with image_item using CDN's x-encrypted-param
|
||||
const expectedAesKeyBase64 = aesKeyBytes.toString('base64');
|
||||
// Step 4: send message with image_item using CDN's x-encrypted-param.
|
||||
// WeChat expects images to include the hex key both directly and
|
||||
// base64-encoded in the media payload.
|
||||
const expectedAesKeyBase64 = Buffer.from(
|
||||
expectedAesKeyHex,
|
||||
'ascii',
|
||||
).toString('base64');
|
||||
expect(mockSendMessage).toHaveBeenCalledWith(
|
||||
'https://api.example.com',
|
||||
'token-abc',
|
||||
@ -337,6 +381,8 @@ describe('sendImage', () => {
|
||||
expect.objectContaining({
|
||||
type: 2, // MessageItemType.IMAGE
|
||||
image_item: expect.objectContaining({
|
||||
aeskey: expectedAesKeyHex,
|
||||
mid_size: encryptedSize,
|
||||
media: {
|
||||
encrypt_query_param: 'cdn-encrypt-param',
|
||||
aes_key: expectedAesKeyBase64,
|
||||
|
||||
@ -12,7 +12,7 @@ import {
|
||||
closeSync,
|
||||
} from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { resolve, extname } from 'node:path';
|
||||
import { resolve, extname, win32, posix } from 'node:path';
|
||||
import { sendMessage, getUploadUrl, uploadToCdn } from './api.js';
|
||||
import { MessageType, MessageState, MessageItemType } from './types.js';
|
||||
import { encryptAesEcb, computeMd5 } from './media.js';
|
||||
@ -45,6 +45,28 @@ export function markdownToPlainText(text: string): string {
|
||||
const ALLOWED_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
|
||||
const MAX_IMAGE_SIZE = 20 * 1024 * 1024; // 20 MB
|
||||
|
||||
function looksLikeWindowsPath(pathValue: string): boolean {
|
||||
return /^[a-zA-Z]:[\\/]/.test(pathValue) || pathValue.startsWith('\\\\');
|
||||
}
|
||||
|
||||
function normalizeWindowsPath(pathValue: string): string {
|
||||
return pathValue.replace(/\//g, '\\');
|
||||
}
|
||||
|
||||
function isInsideAllowedDir(realPath: string, allowedDir: string): boolean {
|
||||
const windowsStyle =
|
||||
looksLikeWindowsPath(realPath) || looksLikeWindowsPath(allowedDir);
|
||||
const pathImpl = windowsStyle ? win32 : posix;
|
||||
const from = windowsStyle ? normalizeWindowsPath(allowedDir) : allowedDir;
|
||||
const to = windowsStyle ? normalizeWindowsPath(realPath) : realPath;
|
||||
const relative = pathImpl.relative(from, to);
|
||||
|
||||
return (
|
||||
relative === '' ||
|
||||
(!relative.startsWith('..') && !pathImpl.isAbsolute(relative))
|
||||
);
|
||||
}
|
||||
|
||||
/** Image magic bytes → MIME type mapping. */
|
||||
export function detectImageMime(data: Buffer): string {
|
||||
if (
|
||||
@ -125,7 +147,7 @@ export function validateImagePath(
|
||||
...workspaceDirs.map((d) => realpathSync(resolve(d)) + '/'),
|
||||
];
|
||||
|
||||
if (!ALLOWED_DIRS.some((dir) => real.startsWith(dir))) {
|
||||
if (!ALLOWED_DIRS.some((dir) => isInsideAllowedDir(real, dir))) {
|
||||
throw new Error(`Image path outside allowed directories: ${real}`);
|
||||
}
|
||||
|
||||
@ -231,9 +253,10 @@ export async function sendImage(params: {
|
||||
const encrypted = encryptAesEcb(fileBuffer, aesKeyBytes);
|
||||
const cdnEncryptParam = await uploadToCdn(uploadParam, filekey, encrypted);
|
||||
|
||||
// Step 4: send message with image_item using CDN's x-encrypted-param
|
||||
// aes_key: base64(raw 16 bytes) for images per protocol
|
||||
const aesKeyBase64 = aesKeyBytes.toString('base64');
|
||||
// Step 4: send message with image_item using CDN's x-encrypted-param.
|
||||
// WeChat image messages expect the AES key as a hex string, with media.aes_key
|
||||
// carrying base64(hex string), not base64(raw bytes).
|
||||
const aesKeyBase64 = Buffer.from(aesKeyHex, 'ascii').toString('base64');
|
||||
|
||||
await sendMessage(baseUrl, token, {
|
||||
to_user_id: to,
|
||||
@ -246,6 +269,8 @@ export async function sendImage(params: {
|
||||
{
|
||||
type: MessageItemType.IMAGE,
|
||||
image_item: {
|
||||
aeskey: aesKeyHex,
|
||||
mid_size: encryptedSize,
|
||||
media: {
|
||||
encrypt_query_param: cdnEncryptParam,
|
||||
aes_key: aesKeyBase64,
|
||||
|
||||
@ -46,13 +46,6 @@ vi.mock('@agentclientprotocol/sdk', () => ({
|
||||
})),
|
||||
ndJsonStream: vi.fn().mockReturnValue({}),
|
||||
RequestError: class RequestError extends Error {
|
||||
code: number;
|
||||
data: unknown;
|
||||
constructor(code: number, message: string, data?: unknown) {
|
||||
super(message);
|
||||
this.code = code;
|
||||
this.data = data;
|
||||
}
|
||||
static authRequired = vi
|
||||
.fn()
|
||||
.mockImplementation((data: unknown, msg: string) => {
|
||||
@ -67,18 +60,6 @@ vi.mock('@agentclientprotocol/sdk', () => ({
|
||||
Object.assign(err, data);
|
||||
return err;
|
||||
});
|
||||
static internalError = vi
|
||||
.fn()
|
||||
.mockImplementation((data: unknown, msg: string) => {
|
||||
const err = new Error(msg);
|
||||
Object.assign(err, { code: -32603, data });
|
||||
return err;
|
||||
});
|
||||
static methodNotFound = vi.fn().mockImplementation((method: string) => {
|
||||
const err = new Error(`Method not found: ${method}`);
|
||||
Object.assign(err, { code: -32601 });
|
||||
return err;
|
||||
});
|
||||
static resourceNotFound = vi.fn().mockImplementation((uri: string) => {
|
||||
const err = new Error(`Resource not found: ${uri}`);
|
||||
Object.assign(err, { code: -32002, data: { uri } });
|
||||
@ -138,34 +119,9 @@ vi.mock('@qwen-code/qwen-code-core', () => ({
|
||||
MCPServerConfig: vi.fn().mockImplementation((...args: unknown[]) => ({
|
||||
_args: args,
|
||||
})),
|
||||
McpTransportPool: vi.fn().mockImplementation(() => ({
|
||||
drainAll: vi.fn().mockResolvedValue({ drained: 0, forced: 0, errors: [] }),
|
||||
getSnapshot: vi.fn().mockReturnValue({
|
||||
total: 0,
|
||||
subprocessCount: 0,
|
||||
byName: {},
|
||||
}),
|
||||
releaseSession: vi.fn(),
|
||||
restartByName: vi.fn().mockResolvedValue([]),
|
||||
getBudget: vi.fn().mockReturnValue(undefined),
|
||||
})),
|
||||
POOLED_TRANSPORTS_DEFAULT: new Set(['stdio', 'websocket']),
|
||||
WorkspaceMcpBudget: vi.fn().mockImplementation(() => ({
|
||||
getReservedCount: vi.fn().mockReturnValue(0),
|
||||
getBudget: vi.fn().mockReturnValue(undefined),
|
||||
getMode: vi.fn().mockReturnValue('off'),
|
||||
getRefusedServerNames: vi.fn().mockReturnValue([]),
|
||||
})),
|
||||
MCP_BUDGET_WARN_FRACTION: 0.75,
|
||||
SessionService: vi.fn(),
|
||||
SESSION_TITLE_MAX_LENGTH: 200,
|
||||
tokenLimit: vi.fn().mockReturnValue(128_000),
|
||||
buildBackgroundEntryLabel: vi.fn(
|
||||
(entry: { description: string; subagentType?: string }) =>
|
||||
entry.subagentType
|
||||
? `${entry.subagentType}: ${entry.description}`
|
||||
: entry.description,
|
||||
),
|
||||
SessionStartSource: {
|
||||
Startup: 'startup',
|
||||
Resume: 'resume',
|
||||
@ -177,38 +133,6 @@ vi.mock('@qwen-code/qwen-code-core', () => ({
|
||||
PromptInputExit: 'prompt_input_exit',
|
||||
Other: 'other',
|
||||
},
|
||||
// T2.8: error classes used by runtime MCP add/remove ext-method handlers
|
||||
McpBudgetWouldExceedError: class McpBudgetWouldExceedError extends Error {
|
||||
readonly code = 'mcp_budget_would_exceed' as const;
|
||||
readonly serverName: string;
|
||||
constructor(serverName: string) {
|
||||
super(`Adding '${serverName}' would exceed workspace MCP budget`);
|
||||
this.name = 'McpBudgetWouldExceedError';
|
||||
this.serverName = serverName;
|
||||
}
|
||||
},
|
||||
McpServerSpawnFailedError: class McpServerSpawnFailedError extends Error {
|
||||
readonly code = 'mcp_server_spawn_failed' as const;
|
||||
readonly serverName: string;
|
||||
readonly details: Record<string, unknown>;
|
||||
constructor(serverName: string, details: Record<string, unknown>) {
|
||||
super(`Failed to spawn MCP server '${serverName}'`);
|
||||
this.name = 'McpServerSpawnFailedError';
|
||||
this.serverName = serverName;
|
||||
this.details = details;
|
||||
}
|
||||
},
|
||||
InvalidMcpConfigError: class InvalidMcpConfigError extends Error {
|
||||
readonly code = 'invalid_config' as const;
|
||||
readonly serverName: string;
|
||||
readonly reason: string;
|
||||
constructor(serverName: string, reason: string) {
|
||||
super(`Invalid MCP server config for '${serverName}': ${reason}`);
|
||||
this.name = 'InvalidMcpConfigError';
|
||||
this.serverName = serverName;
|
||||
this.reason = reason;
|
||||
}
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock('./runtimeOutputDirContext.js', () => ({
|
||||
@ -243,30 +167,6 @@ vi.mock('../config/settings.js', () => ({
|
||||
loadSettings: vi.fn(),
|
||||
}));
|
||||
vi.mock('../config/config.js', () => ({ loadCliConfig: vi.fn() }));
|
||||
vi.mock('../ui/commands/contextCommand.js', () => ({
|
||||
collectContextData: vi.fn().mockResolvedValue({
|
||||
modelName: 'm',
|
||||
showDetails: true,
|
||||
contextWindowSize: 128000,
|
||||
apiTotalTokens: 1000,
|
||||
apiCachedTokens: 200,
|
||||
systemPromptTokens: 500,
|
||||
allToolsTokens: 300,
|
||||
displayBuiltinToolsTokens: 100,
|
||||
displayMcpToolsTokens: 200,
|
||||
skillToolDefinitionTokens: 0,
|
||||
loadedSkillBodiesTokens: 0,
|
||||
memoryFilesTokens: 50,
|
||||
categories: [],
|
||||
builtinTools: [],
|
||||
mcpTools: [],
|
||||
memoryFiles: [],
|
||||
skills: [],
|
||||
}),
|
||||
formatContextUsageText: vi
|
||||
.fn()
|
||||
.mockReturnValue('## Context Usage\nformatted'),
|
||||
}));
|
||||
vi.mock('./session/Session.js', () => ({
|
||||
Session: vi.fn(),
|
||||
buildAvailableCommandsSnapshot: vi.fn().mockResolvedValue({
|
||||
@ -301,17 +201,13 @@ import {
|
||||
getMCPDiscoveryState,
|
||||
getMCPServerStatus,
|
||||
tokenLimit,
|
||||
McpBudgetWouldExceedError,
|
||||
} from '@qwen-code/qwen-code-core';
|
||||
import type { McpServer } from '@agentclientprotocol/sdk';
|
||||
import { AgentSideConnection } from '@agentclientprotocol/sdk';
|
||||
import { loadSettings } from '../config/settings.js';
|
||||
import { loadCliConfig } from '../config/config.js';
|
||||
import { Session, buildAvailableCommandsSnapshot } from './session/Session.js';
|
||||
import {
|
||||
SERVE_STATUS_EXT_METHODS,
|
||||
SERVE_CONTROL_EXT_METHODS,
|
||||
} from '../serve/status.js';
|
||||
import { SERVE_STATUS_EXT_METHODS } from '../serve/status.js';
|
||||
import { buildAuthMethods } from './authMethods.js';
|
||||
|
||||
describe('runAcpAgent shutdown cleanup', () => {
|
||||
@ -861,8 +757,6 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
|
||||
getCurrentAuthType: vi.fn().mockReturnValue('api-key'),
|
||||
}),
|
||||
refreshAuth: vi.fn().mockResolvedValue(undefined),
|
||||
getWorkspaceContext: vi.fn().mockReturnValue({}),
|
||||
getDebugMode: vi.fn().mockReturnValue(false),
|
||||
} as unknown as Config;
|
||||
|
||||
processExitSpy = vi
|
||||
@ -1566,76 +1460,6 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
|
||||
it('status ext methods expose live session context and supported commands', async () => {
|
||||
const sessionId = '11111111-1111-1111-1111-111111111111';
|
||||
const innerConfig = await setupSessionMocks(sessionId);
|
||||
const dateNowSpy = vi.spyOn(Date, 'now').mockReturnValue(5_000);
|
||||
Object.assign(innerConfig, {
|
||||
getBackgroundTaskRegistry: vi.fn().mockReturnValue({
|
||||
getAll: vi.fn().mockReturnValue([
|
||||
{
|
||||
kind: 'agent',
|
||||
id: 'agent-1',
|
||||
agentId: 'agent-1',
|
||||
description: 'Investigate streaming',
|
||||
status: 'paused',
|
||||
startTime: 1_000,
|
||||
outputFile: '/tmp/agent-1.jsonl',
|
||||
outputOffset: 12,
|
||||
notified: false,
|
||||
abortController: new AbortController(),
|
||||
subagentType: 'reviewer',
|
||||
isBackgrounded: true,
|
||||
resumeBlockedReason: 'approval required',
|
||||
pendingMessages: ['secret queue'],
|
||||
},
|
||||
]),
|
||||
}),
|
||||
getBackgroundShellRegistry: vi.fn().mockReturnValue({
|
||||
getAll: vi.fn().mockReturnValue([
|
||||
{
|
||||
kind: 'shell',
|
||||
id: 'shell-1',
|
||||
shellId: 'shell-1',
|
||||
description: 'npm test',
|
||||
status: 'completed',
|
||||
startTime: 3_000,
|
||||
endTime: 4_500,
|
||||
outputFile: '/tmp/shell-1.log',
|
||||
outputPath: '/tmp/shell-1.log',
|
||||
outputOffset: 8,
|
||||
notified: true,
|
||||
abortController: new AbortController(),
|
||||
command: 'npm test',
|
||||
cwd: '/tmp',
|
||||
pid: 123,
|
||||
exitCode: 0,
|
||||
},
|
||||
]),
|
||||
}),
|
||||
getMonitorRegistry: vi.fn().mockReturnValue({
|
||||
getAll: vi.fn().mockReturnValue([
|
||||
{
|
||||
kind: 'monitor',
|
||||
id: 'monitor-1',
|
||||
monitorId: 'monitor-1',
|
||||
description: 'watch logs',
|
||||
status: 'failed',
|
||||
startTime: 2_000,
|
||||
endTime: 2_500,
|
||||
outputFile: '/tmp/monitor-1.log',
|
||||
outputOffset: 0,
|
||||
notified: false,
|
||||
abortController: new AbortController(),
|
||||
command: 'tail -f app.log',
|
||||
pid: 456,
|
||||
eventCount: 3,
|
||||
lastEventTime: 2_400,
|
||||
droppedLines: 1,
|
||||
error: 'boom',
|
||||
ownerAgentId: 'agent-1',
|
||||
idleTimer: {},
|
||||
},
|
||||
]),
|
||||
}),
|
||||
});
|
||||
vi.mocked(buildAvailableCommandsSnapshot).mockResolvedValueOnce({
|
||||
availableCommands: [
|
||||
{
|
||||
@ -1669,13 +1493,6 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
|
||||
SERVE_STATUS_EXT_METHODS.sessionSupportedCommands,
|
||||
{ sessionId },
|
||||
);
|
||||
const tasks = await agent.extMethod(SERVE_STATUS_EXT_METHODS.sessionTasks, {
|
||||
sessionId,
|
||||
});
|
||||
const contextUsage = await agent.extMethod(
|
||||
SERVE_STATUS_EXT_METHODS.sessionContextUsage,
|
||||
{ sessionId, detail: true },
|
||||
);
|
||||
|
||||
expect(context).toMatchObject({
|
||||
v: 1,
|
||||
@ -1698,75 +1515,8 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
|
||||
],
|
||||
availableSkills: ['review'],
|
||||
});
|
||||
expect(tasks).toEqual({
|
||||
v: 1,
|
||||
sessionId,
|
||||
now: 5_000,
|
||||
tasks: [
|
||||
{
|
||||
kind: 'agent',
|
||||
id: 'agent-1',
|
||||
label: 'reviewer: Investigate streaming',
|
||||
description: 'Investigate streaming',
|
||||
status: 'paused',
|
||||
startTime: 1_000,
|
||||
runtimeMs: 4_000,
|
||||
outputFile: '/tmp/agent-1.jsonl',
|
||||
subagentType: 'reviewer',
|
||||
isBackgrounded: true,
|
||||
resumeBlockedReason: 'approval required',
|
||||
},
|
||||
{
|
||||
kind: 'monitor',
|
||||
id: 'monitor-1',
|
||||
label: 'watch logs',
|
||||
description: 'watch logs',
|
||||
status: 'failed',
|
||||
startTime: 2_000,
|
||||
endTime: 2_500,
|
||||
runtimeMs: 500,
|
||||
command: 'tail -f app.log',
|
||||
pid: 456,
|
||||
eventCount: 3,
|
||||
lastEventTime: 2_400,
|
||||
droppedLines: 1,
|
||||
error: 'boom',
|
||||
ownerAgentId: 'agent-1',
|
||||
},
|
||||
{
|
||||
kind: 'shell',
|
||||
id: 'shell-1',
|
||||
label: 'npm test',
|
||||
description: 'npm test',
|
||||
status: 'completed',
|
||||
startTime: 3_000,
|
||||
endTime: 4_500,
|
||||
runtimeMs: 1_500,
|
||||
outputFile: '/tmp/shell-1.log',
|
||||
command: 'npm test',
|
||||
cwd: '/tmp',
|
||||
pid: 123,
|
||||
exitCode: 0,
|
||||
},
|
||||
],
|
||||
});
|
||||
expect(JSON.stringify(tasks)).not.toContain('abortController');
|
||||
expect(JSON.stringify(tasks)).not.toContain('outputOffset');
|
||||
expect(JSON.stringify(tasks)).not.toContain('pendingMessages');
|
||||
expect(JSON.stringify(tasks)).not.toContain('idleTimer');
|
||||
expect(contextUsage).toMatchObject({
|
||||
v: 1,
|
||||
sessionId,
|
||||
workspaceCwd: '/tmp',
|
||||
usage: {
|
||||
modelName: 'm',
|
||||
showDetails: true,
|
||||
},
|
||||
formattedText: expect.stringContaining('## Context Usage'),
|
||||
});
|
||||
expect(buildAvailableCommandsSnapshot).toHaveBeenCalledWith(innerConfig);
|
||||
|
||||
dateNowSpy.mockRestore();
|
||||
mockConnectionState.resolve();
|
||||
await agentPromise;
|
||||
});
|
||||
@ -1825,10 +1575,6 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
|
||||
|
||||
expect(mockConfig.initialize).toHaveBeenCalledWith({
|
||||
skipGeminiInitialization: true,
|
||||
// F2 (#4175 commit 6 review fix — claude-opus-4-7 W119): also
|
||||
// pins that the bootstrap path opts out of MCP discovery (so
|
||||
// bootstrap + per-session don't double-spawn N stdio servers).
|
||||
skipMcpDiscovery: true,
|
||||
});
|
||||
|
||||
mockConnectionState.resolve();
|
||||
@ -1872,10 +1618,6 @@ describe('QwenAgent MCP SSE/HTTP support', () => {
|
||||
|
||||
expect(mockConfig.initialize).toHaveBeenCalledWith({
|
||||
skipGeminiInitialization: true,
|
||||
// F2 (#4175 commit 6 review fix — claude-opus-4-7 W119): also
|
||||
// pins that the bootstrap path opts out of MCP discovery (so
|
||||
// bootstrap + per-session don't double-spawn N stdio servers).
|
||||
skipMcpDiscovery: true,
|
||||
});
|
||||
expect(initialize).toHaveBeenCalledTimes(1);
|
||||
expect(fireSessionStartEvent).toHaveBeenCalledTimes(1);
|
||||
@ -2626,8 +2368,6 @@ describe('QwenAgent extMethod renameSession routing', () => {
|
||||
getCurrentAuthType: vi.fn().mockReturnValue('api-key'),
|
||||
}),
|
||||
refreshAuth: vi.fn().mockResolvedValue(undefined),
|
||||
getWorkspaceContext: vi.fn().mockReturnValue({}),
|
||||
getDebugMode: vi.fn().mockReturnValue(false),
|
||||
} as unknown as Config;
|
||||
});
|
||||
|
||||
@ -2855,8 +2595,6 @@ describe('QwenAgent loadSession / unstable_resumeSession', () => {
|
||||
getCurrentAuthType: vi.fn().mockReturnValue('api-key'),
|
||||
}),
|
||||
refreshAuth: vi.fn().mockResolvedValue(undefined),
|
||||
getWorkspaceContext: vi.fn().mockReturnValue({}),
|
||||
getDebugMode: vi.fn().mockReturnValue(false),
|
||||
} as unknown as Config;
|
||||
|
||||
processExitSpy = vi
|
||||
@ -3095,194 +2833,3 @@ describe('QwenAgent loadSession / unstable_resumeSession', () => {
|
||||
await agentPromise;
|
||||
});
|
||||
});
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// T2.8 (#4514): extMethod runtime-add / runtime-remove
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
describe('QwenAgent extMethod runtime MCP add/remove (T2.8)', () => {
|
||||
let capturedAgentFactory:
|
||||
| ((conn: { closed: Promise<void> }) => {
|
||||
initialize: (args: Record<string, unknown>) => Promise<unknown>;
|
||||
extMethod: (
|
||||
method: string,
|
||||
args: Record<string, unknown>,
|
||||
) => Promise<Record<string, unknown>>;
|
||||
})
|
||||
| undefined;
|
||||
|
||||
let mockConfig: Config;
|
||||
let processExitSpy: MockInstance<typeof process.exit>;
|
||||
let stdinDestroySpy: MockInstance<typeof process.stdin.destroy>;
|
||||
let stdoutDestroySpy: MockInstance<typeof process.stdout.destroy>;
|
||||
|
||||
const mockArgv = {} as CliArgs;
|
||||
const mockSettings = {
|
||||
merged: { mcpServers: {} },
|
||||
} as unknown as LoadedSettings;
|
||||
|
||||
let mockManager: {
|
||||
addRuntimeMcpServer: ReturnType<typeof vi.fn>;
|
||||
removeRuntimeMcpServer: ReturnType<typeof vi.fn>;
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mockConnectionState.reset();
|
||||
capturedAgentFactory = undefined;
|
||||
|
||||
mockManager = {
|
||||
addRuntimeMcpServer: vi.fn(),
|
||||
removeRuntimeMcpServer: vi.fn(),
|
||||
};
|
||||
|
||||
vi.mocked(AgentSideConnection).mockImplementation((factory: unknown) => {
|
||||
capturedAgentFactory = factory as typeof capturedAgentFactory;
|
||||
return {
|
||||
get closed() {
|
||||
return mockConnectionState.promise;
|
||||
},
|
||||
} as unknown as InstanceType<typeof AgentSideConnection>;
|
||||
});
|
||||
|
||||
mockConfig = {
|
||||
initialize: vi.fn().mockResolvedValue(undefined),
|
||||
waitForMcpReady: vi.fn().mockResolvedValue(undefined),
|
||||
getHookSystem: vi.fn().mockReturnValue(undefined),
|
||||
getDisableAllHooks: vi.fn().mockReturnValue(false),
|
||||
hasHooksForEvent: vi.fn().mockReturnValue(false),
|
||||
getModel: vi.fn().mockReturnValue('test-model'),
|
||||
getModelsConfig: vi.fn().mockReturnValue({
|
||||
getCurrentAuthType: vi.fn().mockReturnValue('api-key'),
|
||||
}),
|
||||
refreshAuth: vi.fn().mockResolvedValue(undefined),
|
||||
getWorkspaceContext: vi.fn().mockReturnValue({}),
|
||||
getDebugMode: vi.fn().mockReturnValue(false),
|
||||
getToolRegistry: vi.fn().mockReturnValue({
|
||||
getMcpClientManager: vi.fn().mockReturnValue(mockManager),
|
||||
}),
|
||||
} as unknown as Config;
|
||||
|
||||
processExitSpy = vi
|
||||
.spyOn(process, 'exit')
|
||||
.mockImplementation((() => undefined) as unknown as typeof process.exit);
|
||||
stdinDestroySpy = vi
|
||||
.spyOn(process.stdin, 'destroy')
|
||||
.mockImplementation(() => process.stdin);
|
||||
stdoutDestroySpy = vi
|
||||
.spyOn(process.stdout, 'destroy')
|
||||
.mockImplementation(() => process.stdout);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
processExitSpy.mockRestore();
|
||||
stdinDestroySpy.mockRestore();
|
||||
stdoutDestroySpy.mockRestore();
|
||||
});
|
||||
|
||||
async function getAgent() {
|
||||
const agentPromise = runAcpAgent(mockConfig, mockSettings, mockArgv);
|
||||
await vi.waitFor(() => expect(capturedAgentFactory).toBeDefined());
|
||||
const agent = capturedAgentFactory!({
|
||||
get closed() {
|
||||
return mockConnectionState.promise;
|
||||
},
|
||||
});
|
||||
return { agent, agentPromise };
|
||||
}
|
||||
|
||||
it('runtime-add forwards to manager and returns success result', async () => {
|
||||
mockManager.addRuntimeMcpServer.mockResolvedValue({
|
||||
name: 'my-srv',
|
||||
transport: 'stdio',
|
||||
replaced: false,
|
||||
shadowedSettings: false,
|
||||
toolCount: 3,
|
||||
originatorClientId: 'client-1',
|
||||
});
|
||||
|
||||
const { agent, agentPromise } = await getAgent();
|
||||
const result = await agent.extMethod(
|
||||
SERVE_CONTROL_EXT_METHODS.workspaceMcpRuntimeAdd,
|
||||
{
|
||||
name: 'my-srv',
|
||||
config: { command: 'node', args: ['server.js'] },
|
||||
originatorClientId: 'client-1',
|
||||
},
|
||||
);
|
||||
|
||||
expect(result).toEqual({
|
||||
name: 'my-srv',
|
||||
transport: 'stdio',
|
||||
replaced: false,
|
||||
shadowedSettings: false,
|
||||
toolCount: 3,
|
||||
originatorClientId: 'client-1',
|
||||
});
|
||||
expect(mockManager.addRuntimeMcpServer).toHaveBeenCalledWith(
|
||||
'my-srv',
|
||||
{ command: 'node', args: ['server.js'] },
|
||||
'client-1',
|
||||
);
|
||||
|
||||
mockConnectionState.resolve();
|
||||
await agentPromise;
|
||||
});
|
||||
|
||||
it('runtime-remove forwards to manager and returns success result', async () => {
|
||||
mockManager.removeRuntimeMcpServer.mockResolvedValue({
|
||||
name: 'my-srv',
|
||||
removed: true,
|
||||
wasShadowingSettings: false,
|
||||
originatorClientId: 'client-2',
|
||||
});
|
||||
|
||||
const { agent, agentPromise } = await getAgent();
|
||||
const result = await agent.extMethod(
|
||||
SERVE_CONTROL_EXT_METHODS.workspaceMcpRuntimeRemove,
|
||||
{
|
||||
name: 'my-srv',
|
||||
originatorClientId: 'client-2',
|
||||
},
|
||||
);
|
||||
|
||||
expect(result).toEqual({
|
||||
name: 'my-srv',
|
||||
removed: true,
|
||||
wasShadowingSettings: false,
|
||||
originatorClientId: 'client-2',
|
||||
});
|
||||
expect(mockManager.removeRuntimeMcpServer).toHaveBeenCalledWith(
|
||||
'my-srv',
|
||||
'client-2',
|
||||
);
|
||||
|
||||
mockConnectionState.resolve();
|
||||
await agentPromise;
|
||||
});
|
||||
|
||||
it('runtime-add propagates McpBudgetWouldExceedError with code field', async () => {
|
||||
// Use the actual mocked class so instanceof checks pass
|
||||
const budgetError = new McpBudgetWouldExceedError('my-srv');
|
||||
mockManager.addRuntimeMcpServer.mockRejectedValue(budgetError);
|
||||
|
||||
const { agent, agentPromise } = await getAgent();
|
||||
const err = await agent
|
||||
.extMethod(SERVE_CONTROL_EXT_METHODS.workspaceMcpRuntimeAdd, {
|
||||
name: 'my-srv',
|
||||
config: { command: 'node', args: ['server.js'] },
|
||||
originatorClientId: 'client-1',
|
||||
})
|
||||
.catch((e: unknown) => e);
|
||||
|
||||
// The error should be a RequestError with data.errorKind preserving
|
||||
// the typed code for the bridge's sendBridgeError mapping
|
||||
expect(err).toBeInstanceOf(Error);
|
||||
const data = (err as { data?: Record<string, unknown> }).data;
|
||||
expect(data?.['errorKind']).toBe('mcp_budget_would_exceed');
|
||||
expect(data?.['serverName']).toBe('my-srv');
|
||||
|
||||
mockConnectionState.resolve();
|
||||
await agentPromise;
|
||||
});
|
||||
});
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -104,40 +104,14 @@ vi.mock('@qwen-code/qwen-code-core', () => ({
|
||||
clearCachedCredentialFile: vi.fn(),
|
||||
QwenOAuth2Event: {},
|
||||
qwenOAuth2Events: { on: vi.fn(), off: vi.fn() },
|
||||
MCP_BUDGET_WARN_FRACTION: 0.75,
|
||||
MCPServerConfig: vi.fn().mockImplementation((...args: unknown[]) => ({
|
||||
_args: args,
|
||||
})),
|
||||
SessionService: vi.fn(),
|
||||
SESSION_TITLE_MAX_LENGTH: 200,
|
||||
tokenLimit: vi.fn(),
|
||||
getMCPDiscoveryState: vi.fn(() => 'not_started'),
|
||||
getMCPServerStatus: vi.fn(() => 'disconnected'),
|
||||
MCPDiscoveryState: {
|
||||
NOT_STARTED: 'not_started',
|
||||
IN_PROGRESS: 'in_progress',
|
||||
COMPLETED: 'completed',
|
||||
},
|
||||
MCPServerStatus: {
|
||||
DISCONNECTED: 'disconnected',
|
||||
CONNECTING: 'connecting',
|
||||
CONNECTED: 'connected',
|
||||
},
|
||||
McpTransportPool: vi.fn().mockImplementation(() => ({
|
||||
acquire: vi.fn(),
|
||||
release: vi.fn(),
|
||||
shutdown: vi.fn().mockResolvedValue(undefined),
|
||||
on: vi.fn(),
|
||||
off: vi.fn(),
|
||||
})),
|
||||
POOLED_TRANSPORTS_DEFAULT: new Set<string>(),
|
||||
SessionStartSource: { Startup: 'startup', Resume: 'resume' },
|
||||
SessionEndReason: { PromptInputExit: 'prompt_input_exit', Other: 'other' },
|
||||
WorkspaceMcpBudget: vi.fn().mockImplementation(() => ({
|
||||
register: vi.fn(),
|
||||
unregister: vi.fn(),
|
||||
snapshot: vi.fn(() => ({})),
|
||||
})),
|
||||
restoreWorktreeContext: mockRestoreWorktreeContext,
|
||||
}));
|
||||
|
||||
@ -261,13 +235,6 @@ describe('QwenAgent loadSession — Phase C worktree context restore', () => {
|
||||
hasHooksForEvent: vi.fn().mockReturnValue(false),
|
||||
getResumedSessionData: vi.fn().mockReturnValue(undefined),
|
||||
getSessionService: vi.fn().mockReturnValue(mockSessionService),
|
||||
getWorkspaceContext: vi.fn().mockReturnValue({
|
||||
getDirectories: vi.fn().mockReturnValue([]),
|
||||
addDirectory: vi.fn(),
|
||||
}),
|
||||
getDebugMode: vi.fn().mockReturnValue(false),
|
||||
getMcpServers: vi.fn().mockReturnValue({}),
|
||||
setMcpBudgetEventCallback: vi.fn(),
|
||||
};
|
||||
}
|
||||
|
||||
@ -305,13 +272,6 @@ describe('QwenAgent loadSession — Phase C worktree context restore', () => {
|
||||
getCurrentAuthType: vi.fn().mockReturnValue('api-key'),
|
||||
}),
|
||||
refreshAuth: vi.fn().mockResolvedValue(undefined),
|
||||
getWorkspaceContext: vi.fn().mockReturnValue({
|
||||
getDirectories: vi.fn().mockReturnValue([]),
|
||||
addDirectory: vi.fn(),
|
||||
}),
|
||||
getDebugMode: vi.fn().mockReturnValue(false),
|
||||
getMcpServers: vi.fn().mockReturnValue({}),
|
||||
setMcpBudgetEventCallback: vi.fn(),
|
||||
} as unknown as Config;
|
||||
|
||||
processExitSpy = vi
|
||||
|
||||
@ -259,11 +259,6 @@ describe('HistoryReplayer', () => {
|
||||
rawInput: { path: '/test.ts' },
|
||||
_meta: {
|
||||
toolName: 'read_file',
|
||||
// #4175 F4 prereq — ToolCallEmitter now stamps provenance
|
||||
// on every tool_call / tool_call_update event so the UI can
|
||||
// dispatch on builtin / mcp / subagent without string-
|
||||
// matching toolName.
|
||||
provenance: 'builtin',
|
||||
timestamp: toEpochMs(record.timestamp),
|
||||
},
|
||||
}),
|
||||
@ -319,8 +314,6 @@ describe('HistoryReplayer', () => {
|
||||
rawOutput: 'File contents here',
|
||||
_meta: {
|
||||
toolName: 'read_file',
|
||||
// #4175 F4 prereq — provenance stamped on update events too.
|
||||
provenance: 'builtin',
|
||||
timestamp: toEpochMs(record.timestamp),
|
||||
},
|
||||
});
|
||||
|
||||
@ -37,22 +37,6 @@ vi.mock('../../nonInteractiveCliCommands.js', () => ({
|
||||
handleSlashCommand: vi.fn(),
|
||||
}));
|
||||
|
||||
// Partial-mock `@qwen-code/qwen-code-core` so the daemon follow-up
|
||||
// suggestion tests below can spy on `generatePromptSuggestion` /
|
||||
// `logPromptSuggestion` without spinning up a real LLM client. Other
|
||||
// existing tests still get the real `CompressionStatus`, `ApprovalMode`,
|
||||
// `AuthType`, etc. via the spread.
|
||||
vi.mock('@qwen-code/qwen-code-core', async () => {
|
||||
const actual = await vi.importActual<
|
||||
typeof import('@qwen-code/qwen-code-core')
|
||||
>('@qwen-code/qwen-code-core');
|
||||
return {
|
||||
...actual,
|
||||
generatePromptSuggestion: vi.fn(),
|
||||
logPromptSuggestion: vi.fn(),
|
||||
};
|
||||
});
|
||||
|
||||
function chatRecord(overrides: Record<string, unknown>): ChatRecord {
|
||||
return {
|
||||
uuid: 'record',
|
||||
@ -212,6 +196,8 @@ describe('Session', () => {
|
||||
sendMessageStream: vi.fn(),
|
||||
addHistory: vi.fn(),
|
||||
getHistory: vi.fn().mockReturnValue([]),
|
||||
getHistoryShallow: vi.fn().mockReturnValue([]),
|
||||
getLastModelMessageText: vi.fn().mockReturnValue(''),
|
||||
setHistory: vi.fn(),
|
||||
truncateHistory: vi.fn(),
|
||||
stripThoughtsFromHistory: vi.fn(),
|
||||
@ -334,68 +320,6 @@ describe('Session', () => {
|
||||
|
||||
expect(mockConfig.setApprovalMode).toHaveBeenCalledWith(expected);
|
||||
});
|
||||
|
||||
it('emits a current_mode_update extNotification after switching (A2)', async () => {
|
||||
await session.setMode({
|
||||
sessionId: 'test-session-id',
|
||||
modeId: 'auto-edit',
|
||||
});
|
||||
|
||||
expect(mockClient.extNotification).toHaveBeenCalledWith(
|
||||
'qwen/notify/session/mode-update',
|
||||
expect.objectContaining({
|
||||
v: 1,
|
||||
sessionId: 'test-session-id',
|
||||
currentModeId: 'auto-edit',
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('rejects an unknown modeId and does NOT touch approval mode (A2)', async () => {
|
||||
await expect(
|
||||
session.setMode({
|
||||
sessionId: 'test-session-id',
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
modeId: 'totally-bogus' as any,
|
||||
}),
|
||||
).rejects.toThrow(/Unknown approval mode/);
|
||||
|
||||
expect(mockConfig.setApprovalMode).not.toHaveBeenCalled();
|
||||
expect(mockClient.extNotification).not.toHaveBeenCalledWith(
|
||||
'qwen/notify/session/mode-update',
|
||||
expect.anything(),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('sendCurrentModeUpdateNotification', () => {
|
||||
// The exit_plan_mode / edit-ProceedAlways path publishes the legacy
|
||||
// `session_update{current_mode_update}` frame itself (via sendUpdate),
|
||||
// so its extNotification must carry `legacyFrameSent: true` to stop the
|
||||
// bridge demux from emitting a second, duplicate legacy frame. Unlike
|
||||
// `setMode` (which omits the flag), a regression dropping it here would
|
||||
// double-publish to the IDE companion. (A2)
|
||||
it('marks the extNotification legacyFrameSent so the demux skips its dual-emit', async () => {
|
||||
await (
|
||||
session as unknown as {
|
||||
sendCurrentModeUpdateNotification: (
|
||||
outcome: core.ToolConfirmationOutcome,
|
||||
) => Promise<void>;
|
||||
}
|
||||
).sendCurrentModeUpdateNotification(
|
||||
core.ToolConfirmationOutcome.ProceedAlways,
|
||||
);
|
||||
|
||||
expect(mockClient.extNotification).toHaveBeenCalledWith(
|
||||
'qwen/notify/session/mode-update',
|
||||
expect.objectContaining({
|
||||
v: 1,
|
||||
sessionId: 'test-session-id',
|
||||
currentModeId: 'auto-edit',
|
||||
legacyFrameSent: true,
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('rewindToTurn', () => {
|
||||
@ -407,6 +331,7 @@ describe('Session', () => {
|
||||
{ role: 'model', parts: [{ text: 'second reply' }] },
|
||||
];
|
||||
vi.mocked(mockChat.getHistory).mockReturnValue(history);
|
||||
vi.mocked(mockChat.getHistoryShallow).mockReturnValue(history);
|
||||
|
||||
const result = session.rewindToTurn(1);
|
||||
|
||||
@ -426,6 +351,7 @@ describe('Session', () => {
|
||||
{ role: 'model', parts: [{ text: 'first reply' }] },
|
||||
];
|
||||
vi.mocked(mockChat.getHistory).mockReturnValue(history);
|
||||
vi.mocked(mockChat.getHistoryShallow).mockReturnValue(history);
|
||||
|
||||
const result = session.rewindToTurn(0);
|
||||
|
||||
@ -434,9 +360,9 @@ describe('Session', () => {
|
||||
});
|
||||
|
||||
it('rejects unreachable user turns', () => {
|
||||
vi.mocked(mockChat.getHistory).mockReturnValue([
|
||||
{ role: 'user', parts: [{ text: 'first' }] },
|
||||
]);
|
||||
const history: Content[] = [{ role: 'user', parts: [{ text: 'first' }] }];
|
||||
vi.mocked(mockChat.getHistory).mockReturnValue(history);
|
||||
vi.mocked(mockChat.getHistoryShallow).mockReturnValue(history);
|
||||
|
||||
expect(() => session.rewindToTurn(2)).toThrow(
|
||||
'Cannot rewind to the requested turn',
|
||||
@ -551,36 +477,6 @@ describe('Session', () => {
|
||||
);
|
||||
});
|
||||
|
||||
it('emits a current_model_update extNotification after switching (A1)', async () => {
|
||||
await session.setModel({
|
||||
sessionId: 'test-session-id',
|
||||
modelId: `qwen3-coder-plus(${AuthType.USE_OPENAI})`,
|
||||
});
|
||||
|
||||
expect(mockClient.extNotification).toHaveBeenCalledWith(
|
||||
'qwen/notify/session/model-update',
|
||||
expect.objectContaining({
|
||||
v: 1,
|
||||
sessionId: 'test-session-id',
|
||||
currentModelId: 'qwen3-coder-plus',
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('does NOT emit the model-update notification when the switch fails (A1)', async () => {
|
||||
switchModelSpy.mockRejectedValueOnce(new Error('switch boom'));
|
||||
await expect(
|
||||
session.setModel({
|
||||
sessionId: 'test-session-id',
|
||||
modelId: `qwen3-coder-plus(${AuthType.USE_OPENAI})`,
|
||||
}),
|
||||
).rejects.toThrow();
|
||||
expect(mockClient.extNotification).not.toHaveBeenCalledWith(
|
||||
'qwen/notify/session/model-update',
|
||||
expect.anything(),
|
||||
);
|
||||
});
|
||||
|
||||
it('rejects empty/whitespace model IDs', async () => {
|
||||
await expect(
|
||||
session.setModel({
|
||||
@ -961,6 +857,8 @@ describe('Session', () => {
|
||||
sendMessageStream: vi.fn().mockResolvedValue(createEmptyStream()),
|
||||
addHistory: vi.fn(),
|
||||
getHistory: vi.fn().mockReturnValue([]),
|
||||
getHistoryShallow: vi.fn().mockReturnValue([]),
|
||||
getLastModelMessageText: vi.fn().mockReturnValue(''),
|
||||
} as unknown as GeminiChat;
|
||||
|
||||
mockChat.sendMessageStream = vi
|
||||
@ -1315,6 +1213,8 @@ describe('Session', () => {
|
||||
sendMessageStream: vi.fn().mockResolvedValue(createEmptyStream()),
|
||||
addHistory: vi.fn(),
|
||||
getHistory: vi.fn().mockReturnValue([]),
|
||||
getHistoryShallow: vi.fn().mockReturnValue([]),
|
||||
getLastModelMessageText: vi.fn().mockReturnValue(''),
|
||||
} as unknown as GeminiChat;
|
||||
mockConfig.getSessionTokenLimit = vi.fn().mockReturnValue(100);
|
||||
mockGeminiClient.tryCompressChat
|
||||
@ -1365,7 +1265,6 @@ describe('Session', () => {
|
||||
});
|
||||
mockClient.sessionUpdate = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(undefined) // emitUserMessage
|
||||
.mockRejectedValueOnce(new Error('client disconnected'));
|
||||
mockChat.sendMessageStream = vi
|
||||
.fn()
|
||||
@ -1435,7 +1334,6 @@ describe('Session', () => {
|
||||
});
|
||||
mockClient.sessionUpdate = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(undefined) // emitUserMessage
|
||||
.mockRejectedValueOnce(new Error('client disconnected'));
|
||||
mockChat.sendMessageStream = vi
|
||||
.fn()
|
||||
@ -1633,6 +1531,9 @@ describe('Session', () => {
|
||||
.mockReturnValue([
|
||||
{ role: 'model', parts: [{ text: 'response text' }] },
|
||||
]);
|
||||
mockChat.getLastModelMessageText = vi
|
||||
.fn()
|
||||
.mockReturnValue('response text');
|
||||
mockChat.sendMessageStream = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(createEmptyStream())
|
||||
@ -1694,6 +1595,9 @@ describe('Session', () => {
|
||||
.mockReturnValue([
|
||||
{ role: 'model', parts: [{ text: 'response text' }] },
|
||||
]);
|
||||
mockChat.getLastModelMessageText = vi
|
||||
.fn()
|
||||
.mockReturnValue('response text');
|
||||
mockChat.sendMessageStream = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(createEmptyStream())
|
||||
@ -1765,6 +1669,9 @@ describe('Session', () => {
|
||||
.mockReturnValue([
|
||||
{ role: 'model', parts: [{ text: 'response text' }] },
|
||||
]);
|
||||
mockChat.getLastModelMessageText = vi
|
||||
.fn()
|
||||
.mockReturnValue('response text');
|
||||
mockChat.sendMessageStream = vi
|
||||
.fn()
|
||||
.mockResolvedValue(createEmptyStream());
|
||||
@ -2515,6 +2422,9 @@ describe('Session', () => {
|
||||
.mockReturnValue([
|
||||
{ role: 'model', parts: [{ text: 'response text' }] },
|
||||
]);
|
||||
mockChat.getLastModelMessageText = vi
|
||||
.fn()
|
||||
.mockReturnValue('response text');
|
||||
|
||||
mockChat.sendMessageStream = vi.fn().mockResolvedValue(
|
||||
createStreamWithChunks([
|
||||
@ -2568,6 +2478,9 @@ describe('Session', () => {
|
||||
.mockReturnValue([
|
||||
{ role: 'model', parts: [{ text: 'response text' }] },
|
||||
]);
|
||||
mockChat.getLastModelMessageText = vi
|
||||
.fn()
|
||||
.mockReturnValue('response text');
|
||||
mockChat.sendMessageStream = vi
|
||||
.fn()
|
||||
.mockResolvedValue(createEmptyStream());
|
||||
@ -2613,6 +2526,9 @@ describe('Session', () => {
|
||||
.mockReturnValue([
|
||||
{ role: 'model', parts: [{ text: 'response text' }] },
|
||||
]);
|
||||
mockChat.getLastModelMessageText = vi
|
||||
.fn()
|
||||
.mockReturnValue('response text');
|
||||
mockChat.sendMessageStream = vi
|
||||
.fn()
|
||||
.mockResolvedValue(createEmptyStream());
|
||||
@ -3229,195 +3145,4 @@ describe('Session', () => {
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('follow-up suggestion (daemon assist push)', () => {
|
||||
let generateMock: ReturnType<typeof vi.fn>;
|
||||
let logMock: ReturnType<typeof vi.fn>;
|
||||
|
||||
beforeEach(() => {
|
||||
generateMock = vi.mocked(core.generatePromptSuggestion);
|
||||
logMock = vi.mocked(core.logPromptSuggestion);
|
||||
generateMock.mockReset();
|
||||
logMock.mockReset();
|
||||
// Enable the feature by default in this describe block; individual
|
||||
// tests override `mockSettings.merged.ui` to exercise the disabled
|
||||
// path.
|
||||
(mockSettings as unknown as { merged: { ui: unknown } }).merged.ui = {
|
||||
enableFollowupSuggestions: true,
|
||||
};
|
||||
vi.mocked(mockChat.getHistory).mockReturnValue([
|
||||
{ role: 'user', parts: [{ text: 'hello' }] },
|
||||
{ role: 'model', parts: [{ text: 'hi back' }] },
|
||||
]);
|
||||
mockChat.sendMessageStream = vi
|
||||
.fn()
|
||||
.mockResolvedValue(createEmptyStream());
|
||||
});
|
||||
|
||||
it('fires prompt-suggestion extNotification after end_turn when enabled', async () => {
|
||||
generateMock.mockResolvedValue({ suggestion: 'Run the tests next?' });
|
||||
|
||||
await session.prompt({
|
||||
sessionId: 'test-session-id',
|
||||
prompt: [{ type: 'text', text: 'hello' }],
|
||||
});
|
||||
|
||||
await vi.waitFor(() => {
|
||||
expect(mockClient.extNotification).toHaveBeenCalledWith(
|
||||
'qwen/notify/session/prompt-suggestion',
|
||||
{
|
||||
v: 1,
|
||||
sessionId: 'test-session-id',
|
||||
suggestion: 'Run the tests next?',
|
||||
promptId: 'test-session-id########1',
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
// The generator received an AbortSignal so the daemon can cancel
|
||||
// mid-flight if the next prompt arrives first.
|
||||
expect(generateMock).toHaveBeenCalledWith(
|
||||
mockConfig,
|
||||
expect.any(Array),
|
||||
expect.any(AbortSignal),
|
||||
expect.objectContaining({ enableCacheSharing: expect.any(Boolean) }),
|
||||
);
|
||||
});
|
||||
|
||||
it('does not emit when the feature is disabled', async () => {
|
||||
(mockSettings as unknown as { merged: { ui: unknown } }).merged.ui = {
|
||||
enableFollowupSuggestions: false,
|
||||
};
|
||||
|
||||
await session.prompt({
|
||||
sessionId: 'test-session-id',
|
||||
prompt: [{ type: 'text', text: 'hello' }],
|
||||
});
|
||||
|
||||
// Give the (skipped) IIFE a chance to run.
|
||||
await new Promise((r) => setTimeout(r, 10));
|
||||
expect(generateMock).not.toHaveBeenCalled();
|
||||
expect(
|
||||
(
|
||||
mockClient.extNotification as ReturnType<typeof vi.fn>
|
||||
).mock.calls.find(
|
||||
([method]) => method === 'qwen/notify/session/prompt-suggestion',
|
||||
),
|
||||
).toBeUndefined();
|
||||
});
|
||||
|
||||
it('does not emit in PLAN approval mode', async () => {
|
||||
mockConfig.getApprovalMode = vi.fn().mockReturnValue(ApprovalMode.PLAN);
|
||||
generateMock.mockResolvedValue({ suggestion: 'something' });
|
||||
|
||||
await session.prompt({
|
||||
sessionId: 'test-session-id',
|
||||
prompt: [{ type: 'text', text: 'hello' }],
|
||||
});
|
||||
|
||||
await new Promise((r) => setTimeout(r, 10));
|
||||
expect(generateMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('logs filterReason via PromptSuggestionEvent when generation is suppressed', async () => {
|
||||
generateMock.mockResolvedValue({
|
||||
suggestion: null,
|
||||
filterReason: 'meta',
|
||||
});
|
||||
|
||||
await session.prompt({
|
||||
sessionId: 'test-session-id',
|
||||
prompt: [{ type: 'text', text: 'hello' }],
|
||||
});
|
||||
|
||||
await vi.waitFor(() => {
|
||||
expect(logMock).toHaveBeenCalledWith(
|
||||
mockConfig,
|
||||
expect.objectContaining({ outcome: 'suppressed', reason: 'meta' }),
|
||||
);
|
||||
});
|
||||
// No extNotification when suggestion is filtered.
|
||||
expect(
|
||||
(
|
||||
mockClient.extNotification as ReturnType<typeof vi.fn>
|
||||
).mock.calls.find(
|
||||
([method]) => method === 'qwen/notify/session/prompt-suggestion',
|
||||
),
|
||||
).toBeUndefined();
|
||||
});
|
||||
|
||||
it('aborts the in-flight generator when a new prompt arrives', async () => {
|
||||
let capturedSignal: AbortSignal | undefined;
|
||||
generateMock
|
||||
.mockImplementationOnce(
|
||||
async (
|
||||
_config: unknown,
|
||||
_history: unknown,
|
||||
signal: AbortSignal,
|
||||
): Promise<{ suggestion: string | null }> => {
|
||||
capturedSignal = signal;
|
||||
return new Promise((resolve) => {
|
||||
signal.addEventListener('abort', () =>
|
||||
resolve({ suggestion: null }),
|
||||
);
|
||||
});
|
||||
},
|
||||
)
|
||||
.mockResolvedValue({ suggestion: null });
|
||||
|
||||
await session.prompt({
|
||||
sessionId: 'test-session-id',
|
||||
prompt: [{ type: 'text', text: 'first' }],
|
||||
});
|
||||
// Wait for the IIFE to actually call generateMock and capture the
|
||||
// signal — without this, the second prompt can race past the
|
||||
// first IIFE's microtask.
|
||||
await vi.waitFor(() => expect(capturedSignal).toBeDefined());
|
||||
expect(capturedSignal!.aborted).toBe(false);
|
||||
|
||||
// Send a second prompt. The followupAbort on the first turn
|
||||
// should fire synchronously at the top of `prompt()`.
|
||||
await session.prompt({
|
||||
sessionId: 'test-session-id',
|
||||
prompt: [{ type: 'text', text: 'second' }],
|
||||
});
|
||||
|
||||
expect(capturedSignal!.aborted).toBe(true);
|
||||
});
|
||||
|
||||
it('aborts the in-flight generator when cancelPendingPrompt is called', async () => {
|
||||
let capturedSignal: AbortSignal | undefined;
|
||||
generateMock
|
||||
.mockImplementationOnce(
|
||||
async (
|
||||
_config: unknown,
|
||||
_history: unknown,
|
||||
signal: AbortSignal,
|
||||
): Promise<{ suggestion: string | null }> => {
|
||||
capturedSignal = signal;
|
||||
return new Promise((resolve) => {
|
||||
signal.addEventListener('abort', () =>
|
||||
resolve({ suggestion: null }),
|
||||
);
|
||||
});
|
||||
},
|
||||
)
|
||||
.mockResolvedValue({ suggestion: null });
|
||||
|
||||
await session.prompt({
|
||||
sessionId: 'test-session-id',
|
||||
prompt: [{ type: 'text', text: 'go' }],
|
||||
});
|
||||
await vi.waitFor(() => expect(capturedSignal).toBeDefined());
|
||||
|
||||
// followupAbort cleanup now runs unconditionally before the
|
||||
// prompt/cron guard — inject a fake pendingPrompt so the call
|
||||
// doesn't throw, but the real assertion is the signal abort.
|
||||
(session as unknown as { pendingPrompt: AbortController }).pendingPrompt =
|
||||
new AbortController();
|
||||
|
||||
await session.cancelPendingPrompt();
|
||||
expect(capturedSignal!.aborted).toBe(true);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@ -26,7 +26,6 @@ import type {
|
||||
AutoModeDecision,
|
||||
AutoModeOutcome,
|
||||
} from '@qwen-code/qwen-code-core';
|
||||
import { NOT_CURRENTLY_GENERATING_CANCEL_MESSAGE } from '@qwen-code/acp-bridge/bridgeErrors';
|
||||
import {
|
||||
AuthType,
|
||||
ApprovalMode,
|
||||
@ -36,11 +35,8 @@ import {
|
||||
DiscoveredMCPTool,
|
||||
StreamEventType,
|
||||
ToolConfirmationOutcome,
|
||||
generatePromptSuggestion,
|
||||
logPromptSuggestion,
|
||||
logToolCall,
|
||||
logUserPrompt,
|
||||
PromptSuggestionEvent,
|
||||
getErrorStatus,
|
||||
UserPromptEvent,
|
||||
readManyFiles,
|
||||
@ -76,8 +72,6 @@ import {
|
||||
shouldFallback,
|
||||
shouldFirePermissionDeniedForAutoMode,
|
||||
shouldRunAutoModeForCall,
|
||||
extractDaemonTraceContext,
|
||||
withInteractionSpan,
|
||||
} from '@qwen-code/qwen-code-core';
|
||||
import { getCommandSubcommandNames } from '../../services/commandMetadata.js';
|
||||
import { getEffectiveSupportedModes } from '../../services/commandUtils.js';
|
||||
@ -298,13 +292,6 @@ export class Session implements SessionContext {
|
||||
* process termination is slow.
|
||||
*/
|
||||
private pendingPromptCompletion: Promise<void> | null = null;
|
||||
/**
|
||||
* Per-turn AbortController for the fire-and-forget follow-up suggestion
|
||||
* generation. Aborted on the top of the next `prompt()` and on
|
||||
* `cancelPendingPrompt()` so a stale suggestion never lands after the
|
||||
* user has moved on. Null when no suggestion generation is in flight.
|
||||
*/
|
||||
private followupAbort: AbortController | null = null;
|
||||
private turn: number = 0;
|
||||
private readonly runtimeBaseDir: string;
|
||||
|
||||
@ -415,7 +402,7 @@ export class Session implements SessionContext {
|
||||
}
|
||||
|
||||
const chat = this.config.getGeminiClient()!.getChat();
|
||||
const apiHistory = chat.getHistory();
|
||||
const apiHistory = chat.getHistoryShallow();
|
||||
const apiTruncateIndex = this.#computeApiTruncationIndexForUserTurn(
|
||||
apiHistory,
|
||||
targetTurnIndex,
|
||||
@ -510,13 +497,8 @@ export class Session implements SessionContext {
|
||||
const hadPrompt = !!this.pendingPrompt;
|
||||
const hadCron = !!this.cronAbortController;
|
||||
|
||||
if (this.followupAbort) {
|
||||
this.followupAbort.abort();
|
||||
this.followupAbort = null;
|
||||
}
|
||||
|
||||
if (!hadPrompt && !hadCron) {
|
||||
throw new Error(NOT_CURRENTLY_GENERATING_CANCEL_MESSAGE);
|
||||
throw new Error('Not currently generating');
|
||||
}
|
||||
|
||||
if (this.pendingPrompt) {
|
||||
@ -552,15 +534,6 @@ export class Session implements SessionContext {
|
||||
const pendingSend = new AbortController();
|
||||
this.pendingPrompt = pendingSend;
|
||||
|
||||
// Abort the previous turn's in-flight follow-up suggestion
|
||||
// generation (if any). Mirrors `pendingPrompt?.abort()` above —
|
||||
// a fresh prompt arriving means any pending suggestion would be
|
||||
// stale before it could ever render.
|
||||
if (this.followupAbort) {
|
||||
this.followupAbort.abort();
|
||||
this.followupAbort = null;
|
||||
}
|
||||
|
||||
// Abort any in-progress cron execution (user prompt takes priority)
|
||||
if (this.cronAbortController) {
|
||||
this.cronAbortController.abort();
|
||||
@ -603,109 +576,12 @@ export class Session implements SessionContext {
|
||||
this.#startCronSchedulerIfNeeded();
|
||||
// Drain any cron prompts that queued while the prompt was active
|
||||
void this.#drainCronQueue();
|
||||
// Fire-and-forget follow-up suggestion generation. Best-effort UX
|
||||
// hint — must not block the prompt response. See
|
||||
// `#maybeEmitFollowupSuggestion` for guards and cancellation.
|
||||
this.#maybeEmitFollowupSuggestion(result);
|
||||
return result;
|
||||
} finally {
|
||||
resolveCompletion();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate a server-side follow-up suggestion for the just-completed
|
||||
* turn and push it to attached clients via the daemon's
|
||||
* `qwen/notify/session/prompt-suggestion` extNotification. Mirrors
|
||||
* the CLI's `AppContainer.tsx` integration: same `generatePromptSuggestion`
|
||||
* call, same `enableCacheSharing` flag forwarding, same curated
|
||||
* history slice (`getHistory(true).slice(-40)`).
|
||||
*
|
||||
* Differences from the CLI:
|
||||
* - Triggers only on `stopReason === 'end_turn'` (the daemon
|
||||
* equivalent of "the assistant finished cleanly"). Cancelled /
|
||||
* errored turns don't get a suggestion.
|
||||
* - Aborted via `this.followupAbort`, which is reset on the next
|
||||
* `prompt()` and on `cancelPendingPrompt()`.
|
||||
* - Filter-reason logging only — accept / dismiss telemetry stays
|
||||
* client-side (the CLI hook owns it).
|
||||
*
|
||||
* Fire-and-forget by design: an unawaited IIFE that swallows its own
|
||||
* errors. A failed suggestion is invisible to the user; a thrown
|
||||
* error here would propagate up through `prompt()` and break the
|
||||
* primary response path.
|
||||
*/
|
||||
#maybeEmitFollowupSuggestion(result: PromptResponse): void {
|
||||
if (result.stopReason !== 'end_turn') return;
|
||||
if (this.settings.merged.ui?.enableFollowupSuggestions !== true) return;
|
||||
if (this.config.getApprovalMode() === ApprovalMode.PLAN) return;
|
||||
|
||||
const chat = this.config.getGeminiClient()?.getChat();
|
||||
if (!chat) return;
|
||||
|
||||
const ac = new AbortController();
|
||||
this.followupAbort = ac;
|
||||
const promptId =
|
||||
this.config.getSessionId() + '########' + String(this.turn);
|
||||
|
||||
void (async () => {
|
||||
try {
|
||||
const fullHistory = chat.getHistory(true);
|
||||
const lastEntry = fullHistory[fullHistory.length - 1];
|
||||
if (!lastEntry || lastEntry.role !== 'model') {
|
||||
debugLogger.debug(
|
||||
'Skipping followup suggestion: last history entry is not model',
|
||||
);
|
||||
return;
|
||||
}
|
||||
const conversationHistory =
|
||||
fullHistory.length > 40 ? fullHistory.slice(-40) : fullHistory;
|
||||
|
||||
const r = await generatePromptSuggestion(
|
||||
this.config,
|
||||
conversationHistory,
|
||||
ac.signal,
|
||||
{
|
||||
enableCacheSharing:
|
||||
this.settings.merged.ui?.enableCacheSharing === true,
|
||||
},
|
||||
);
|
||||
if (ac.signal.aborted) return;
|
||||
if (r.suggestion) {
|
||||
await this.client.extNotification(
|
||||
'qwen/notify/session/prompt-suggestion',
|
||||
{
|
||||
v: 1,
|
||||
sessionId: this.sessionId,
|
||||
suggestion: r.suggestion,
|
||||
promptId,
|
||||
},
|
||||
);
|
||||
} else if (r.filterReason) {
|
||||
// Mirror the CLI's suppression analytics path so server-side
|
||||
// generations are observable in the same telemetry stream.
|
||||
logPromptSuggestion(
|
||||
this.config,
|
||||
new PromptSuggestionEvent({
|
||||
outcome: 'suppressed',
|
||||
reason: r.filterReason,
|
||||
}),
|
||||
);
|
||||
}
|
||||
} catch (error) {
|
||||
if (ac.signal.aborted) {
|
||||
debugLogger.debug('Follow-up suggestion generation aborted');
|
||||
} else {
|
||||
debugLogger.warn('Follow-up suggestion generation failed', error);
|
||||
}
|
||||
} finally {
|
||||
if (this.followupAbort === ac) {
|
||||
this.followupAbort = null;
|
||||
}
|
||||
}
|
||||
})();
|
||||
}
|
||||
|
||||
async #executePrompt(
|
||||
params: PromptRequest,
|
||||
pendingSend: AbortController,
|
||||
@ -718,290 +594,270 @@ export class Session implements SessionContext {
|
||||
this.turn += 1;
|
||||
|
||||
const promptId = this.config.getSessionId() + '########' + this.turn;
|
||||
const parentContext = extractDaemonTraceContext(params);
|
||||
|
||||
return await withInteractionSpan(
|
||||
// Extract text from all text blocks to construct the full prompt text for logging
|
||||
const promptText = params.prompt
|
||||
.filter((block) => block.type === 'text')
|
||||
.map((block) => (block.type === 'text' ? block.text : ''))
|
||||
.join(' ');
|
||||
|
||||
// Log user prompt
|
||||
logUserPrompt(
|
||||
this.config,
|
||||
{
|
||||
new UserPromptEvent(
|
||||
promptText.length,
|
||||
promptId,
|
||||
model: this.config.getModel(),
|
||||
messageType: 'acp_prompt',
|
||||
...(parentContext ? { parentContext } : {}),
|
||||
},
|
||||
async () => {
|
||||
// Extract text from all text blocks to construct the full prompt text for logging
|
||||
const promptText = params.prompt
|
||||
.filter((block) => block.type === 'text')
|
||||
.map((block) => (block.type === 'text' ? block.text : ''))
|
||||
.join(' ');
|
||||
this.config.getContentGeneratorConfig()?.authType,
|
||||
promptText,
|
||||
),
|
||||
);
|
||||
|
||||
// Log user prompt
|
||||
logUserPrompt(
|
||||
this.config,
|
||||
new UserPromptEvent(
|
||||
promptText.length,
|
||||
promptId,
|
||||
this.config.getContentGeneratorConfig()?.authType,
|
||||
promptText,
|
||||
),
|
||||
// record user message for session management
|
||||
this.config.getChatRecordingService()?.recordUserMessage(promptText);
|
||||
|
||||
// Check if the input contains a slash command
|
||||
// Extract text from the first text block if present
|
||||
const firstTextBlock = params.prompt.find(
|
||||
(block) => block.type === 'text',
|
||||
);
|
||||
const inputText = firstTextBlock?.text || '';
|
||||
|
||||
let parts: Part[] | null;
|
||||
|
||||
if (isSlashCommand(inputText)) {
|
||||
// Handle slash command in ACP mode using capability-based filtering
|
||||
const slashCommandResult = await handleSlashCommand(
|
||||
inputText,
|
||||
pendingSend,
|
||||
this.config,
|
||||
this.settings,
|
||||
);
|
||||
|
||||
parts = await this.#processSlashCommandResult(
|
||||
slashCommandResult,
|
||||
params.prompt,
|
||||
);
|
||||
|
||||
// If parts is null, the command was fully handled (e.g., /summary completed)
|
||||
// Return early without sending to the model
|
||||
if (parts === null) {
|
||||
return { stopReason: 'end_turn' };
|
||||
}
|
||||
} else {
|
||||
// Normal processing for non-slash commands
|
||||
parts = await this.#resolvePrompt(params.prompt, pendingSend.signal);
|
||||
}
|
||||
|
||||
// Fire UserPromptSubmit hook through MessageBus (aligned with core path in client.ts)
|
||||
const hooksEnabled = !this.config.getDisableAllHooks?.();
|
||||
const messageBus = this.config.getMessageBus?.();
|
||||
if (
|
||||
hooksEnabled &&
|
||||
messageBus &&
|
||||
this.config.hasHooksForEvent?.('UserPromptSubmit')
|
||||
) {
|
||||
const response = await messageBus.request<
|
||||
HookExecutionRequest,
|
||||
HookExecutionResponse
|
||||
>(
|
||||
{
|
||||
type: MessageBusType.HOOK_EXECUTION_REQUEST,
|
||||
eventName: 'UserPromptSubmit',
|
||||
input: {
|
||||
prompt: promptText,
|
||||
},
|
||||
signal: pendingSend.signal,
|
||||
},
|
||||
MessageBusType.HOOK_EXECUTION_RESPONSE,
|
||||
);
|
||||
const hookOutput = response.output
|
||||
? createHookOutput('UserPromptSubmit', response.output)
|
||||
: undefined;
|
||||
|
||||
if (
|
||||
hookOutput?.isBlockingDecision() ||
|
||||
hookOutput?.shouldStopExecution()
|
||||
) {
|
||||
// Hook blocked the prompt - send notification to UI and return
|
||||
const blockReason =
|
||||
hookOutput?.getEffectiveReason() || 'No reason provided';
|
||||
await this.messageEmitter.emitAgentMessage(
|
||||
`🚫 **UserPromptSubmit blocked**: ${blockReason}`,
|
||||
);
|
||||
return { stopReason: 'end_turn' };
|
||||
}
|
||||
|
||||
// record user message for session management
|
||||
this.config
|
||||
.getChatRecordingService()
|
||||
?.recordUserMessage(promptText);
|
||||
// Add additional context from hooks to the request
|
||||
const additionalContext = hookOutput?.getAdditionalContext();
|
||||
if (additionalContext) {
|
||||
parts = [...parts, { text: additionalContext }];
|
||||
}
|
||||
}
|
||||
|
||||
// Check if the input contains a slash command
|
||||
// Extract text from the first text block if present
|
||||
const firstTextBlock = params.prompt.find(
|
||||
(block) => block.type === 'text',
|
||||
// Prepend session-level system reminders (plan mode / subagent /
|
||||
// arena) so the model sees them, matching the behaviour of
|
||||
// `GeminiClient.sendMessageStream` in the CLI/TUI path. Without this,
|
||||
// plan mode in ACP has no effect because the model never learns it
|
||||
// should avoid edits (#1151).
|
||||
const systemReminders = await this.#buildInitialSystemReminders();
|
||||
if (systemReminders.length > 0) {
|
||||
parts = [...systemReminders, ...parts];
|
||||
}
|
||||
|
||||
// Phase C: one-shot worktree restore notice, set by acpAgent on
|
||||
// --resume / loadSession when the session's worktree is still alive.
|
||||
// Prepended exactly once, then cleared so it doesn't repeat on
|
||||
// subsequent turns.
|
||||
if (this.pendingWorktreeNotice) {
|
||||
parts = [
|
||||
{
|
||||
text: `<system-reminder>\n${this.pendingWorktreeNotice}\n</system-reminder>\n\n`,
|
||||
},
|
||||
...parts,
|
||||
];
|
||||
this.pendingWorktreeNotice = null;
|
||||
}
|
||||
|
||||
let nextMessage: Content | null = { role: 'user', parts };
|
||||
|
||||
while (nextMessage !== null) {
|
||||
if (pendingSend.signal.aborted) {
|
||||
this.#getCurrentChat().addHistory(nextMessage);
|
||||
return { stopReason: 'cancelled' };
|
||||
}
|
||||
|
||||
const functionCalls: FunctionCall[] = [];
|
||||
let usageMetadata: GenerateContentResponseUsageMetadata | null = null;
|
||||
const streamStartTime = Date.now();
|
||||
|
||||
try {
|
||||
const sendResult = await this.#sendMessageStreamWithAutoCompression(
|
||||
promptId,
|
||||
nextMessage?.parts ?? [],
|
||||
pendingSend.signal,
|
||||
);
|
||||
const inputText = firstTextBlock?.text || '';
|
||||
|
||||
let parts: Part[] | null;
|
||||
|
||||
if (isSlashCommand(inputText)) {
|
||||
// Handle slash command in ACP mode using capability-based filtering
|
||||
const slashCommandResult = await handleSlashCommand(
|
||||
inputText,
|
||||
pendingSend,
|
||||
this.config,
|
||||
this.settings,
|
||||
);
|
||||
|
||||
parts = await this.#processSlashCommandResult(
|
||||
slashCommandResult,
|
||||
params.prompt,
|
||||
);
|
||||
|
||||
// If parts is null, the command was fully handled (e.g., /summary completed)
|
||||
// Return early without sending to the model
|
||||
if (parts === null) {
|
||||
return { stopReason: 'end_turn' };
|
||||
}
|
||||
} else {
|
||||
// Normal processing for non-slash commands
|
||||
parts = await this.#resolvePrompt(
|
||||
params.prompt,
|
||||
pendingSend.signal,
|
||||
if (!sendResult.responseStream) {
|
||||
this.#preserveUnsentMessageHistory(
|
||||
nextMessage,
|
||||
sendResult.stopReason === 'cancelled',
|
||||
);
|
||||
return { stopReason: sendResult.stopReason };
|
||||
}
|
||||
const responseStream = sendResult.responseStream;
|
||||
nextMessage = null;
|
||||
|
||||
// Fire UserPromptSubmit hook through MessageBus (aligned with core path in client.ts)
|
||||
const hooksEnabled = !this.config.getDisableAllHooks?.();
|
||||
const messageBus = this.config.getMessageBus?.();
|
||||
if (
|
||||
hooksEnabled &&
|
||||
messageBus &&
|
||||
this.config.hasHooksForEvent?.('UserPromptSubmit')
|
||||
) {
|
||||
const response = await messageBus.request<
|
||||
HookExecutionRequest,
|
||||
HookExecutionResponse
|
||||
>(
|
||||
{
|
||||
type: MessageBusType.HOOK_EXECUTION_REQUEST,
|
||||
eventName: 'UserPromptSubmit',
|
||||
input: {
|
||||
prompt: promptText,
|
||||
},
|
||||
signal: pendingSend.signal,
|
||||
},
|
||||
MessageBusType.HOOK_EXECUTION_RESPONSE,
|
||||
);
|
||||
const hookOutput = response.output
|
||||
? createHookOutput('UserPromptSubmit', response.output)
|
||||
: undefined;
|
||||
|
||||
if (
|
||||
hookOutput?.isBlockingDecision() ||
|
||||
hookOutput?.shouldStopExecution()
|
||||
) {
|
||||
// Hook blocked the prompt - send notification to UI and return
|
||||
const blockReason =
|
||||
hookOutput?.getEffectiveReason() || 'No reason provided';
|
||||
await this.messageEmitter.emitAgentMessage(
|
||||
`🚫 **UserPromptSubmit blocked**: ${blockReason}`,
|
||||
);
|
||||
return { stopReason: 'end_turn' };
|
||||
}
|
||||
|
||||
// Add additional context from hooks to the request
|
||||
const additionalContext = hookOutput?.getAdditionalContext();
|
||||
if (additionalContext) {
|
||||
parts = [...parts, { text: additionalContext }];
|
||||
}
|
||||
}
|
||||
|
||||
// Prepend session-level system reminders (plan mode / subagent /
|
||||
// arena) so the model sees them, matching the behaviour of
|
||||
// `GeminiClient.sendMessageStream` in the CLI/TUI path. Without this,
|
||||
// plan mode in ACP has no effect because the model never learns it
|
||||
// should avoid edits (#1151).
|
||||
const systemReminders = await this.#buildInitialSystemReminders();
|
||||
if (systemReminders.length > 0) {
|
||||
parts = [...systemReminders, ...parts];
|
||||
}
|
||||
|
||||
// Phase C: one-shot worktree restore notice, set by acpAgent on
|
||||
// --resume / loadSession when the session's worktree is still alive.
|
||||
// Prepended exactly once, then cleared so it doesn't repeat on
|
||||
// subsequent turns.
|
||||
if (this.pendingWorktreeNotice) {
|
||||
parts = [
|
||||
{
|
||||
text: `<system-reminder>\n${this.pendingWorktreeNotice}\n</system-reminder>\n\n`,
|
||||
},
|
||||
...parts,
|
||||
];
|
||||
this.pendingWorktreeNotice = null;
|
||||
}
|
||||
|
||||
let nextMessage: Content | null = { role: 'user', parts };
|
||||
|
||||
while (nextMessage !== null) {
|
||||
for await (const resp of responseStream) {
|
||||
if (pendingSend.signal.aborted) {
|
||||
this.#getCurrentChat().addHistory(nextMessage);
|
||||
return { stopReason: 'cancelled' };
|
||||
}
|
||||
|
||||
const functionCalls: FunctionCall[] = [];
|
||||
let usageMetadata: GenerateContentResponseUsageMetadata | null =
|
||||
null;
|
||||
const streamStartTime = Date.now();
|
||||
if (
|
||||
resp.type === StreamEventType.CHUNK &&
|
||||
resp.value.candidates &&
|
||||
resp.value.candidates.length > 0
|
||||
) {
|
||||
const candidate = resp.value.candidates[0];
|
||||
for (const part of candidate.content?.parts ?? []) {
|
||||
if (!part.text) {
|
||||
continue;
|
||||
}
|
||||
|
||||
try {
|
||||
const sendResult =
|
||||
await this.#sendMessageStreamWithAutoCompression(
|
||||
promptId,
|
||||
nextMessage?.parts ?? [],
|
||||
pendingSend.signal,
|
||||
this.messageEmitter.emitMessage(
|
||||
part.text,
|
||||
'assistant',
|
||||
part.thought,
|
||||
);
|
||||
if (!sendResult.responseStream) {
|
||||
this.#preserveUnsentMessageHistory(
|
||||
nextMessage,
|
||||
sendResult.stopReason === 'cancelled',
|
||||
);
|
||||
return { stopReason: sendResult.stopReason };
|
||||
}
|
||||
const responseStream = sendResult.responseStream;
|
||||
nextMessage = null;
|
||||
}
|
||||
|
||||
for await (const resp of responseStream) {
|
||||
if (pendingSend.signal.aborted) {
|
||||
return { stopReason: 'cancelled' };
|
||||
}
|
||||
if (
|
||||
resp.type === StreamEventType.CHUNK &&
|
||||
resp.value.usageMetadata
|
||||
) {
|
||||
usageMetadata = resp.value.usageMetadata;
|
||||
}
|
||||
|
||||
if (
|
||||
resp.type === StreamEventType.CHUNK &&
|
||||
resp.value.candidates &&
|
||||
resp.value.candidates.length > 0
|
||||
) {
|
||||
const candidate = resp.value.candidates[0];
|
||||
for (const part of candidate.content?.parts ?? []) {
|
||||
if (!part.text) {
|
||||
continue;
|
||||
}
|
||||
if (
|
||||
resp.type === StreamEventType.CHUNK &&
|
||||
resp.value.functionCalls
|
||||
) {
|
||||
functionCalls.push(...resp.value.functionCalls);
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
// Fire StopFailure hook (fire-and-forget, replaces Stop event for API errors)
|
||||
// Aligned with useGeminiStream.ts handleFinishedWithErrorEvent
|
||||
const errorStatus = getErrorStatus(error);
|
||||
const errorMessage =
|
||||
error instanceof Error ? error.message : String(error);
|
||||
const errorType = classifyApiError({
|
||||
message: errorMessage,
|
||||
status: errorStatus,
|
||||
});
|
||||
|
||||
this.messageEmitter.emitMessage(
|
||||
part.text,
|
||||
'assistant',
|
||||
part.thought,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (
|
||||
resp.type === StreamEventType.CHUNK &&
|
||||
resp.value.usageMetadata
|
||||
) {
|
||||
usageMetadata = resp.value.usageMetadata;
|
||||
}
|
||||
|
||||
if (
|
||||
resp.type === StreamEventType.CHUNK &&
|
||||
resp.value.functionCalls
|
||||
) {
|
||||
functionCalls.push(...resp.value.functionCalls);
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
// Fire StopFailure hook (fire-and-forget, replaces Stop event for API errors)
|
||||
// Aligned with useGeminiStream.ts handleFinishedWithErrorEvent
|
||||
const errorStatus = getErrorStatus(error);
|
||||
const errorMessage =
|
||||
error instanceof Error ? error.message : String(error);
|
||||
const errorType = classifyApiError({
|
||||
message: errorMessage,
|
||||
status: errorStatus,
|
||||
const hookSystem = this.config.getHookSystem?.();
|
||||
const hooksEnabledForStopFailure =
|
||||
!this.config.getDisableAllHooks?.();
|
||||
if (
|
||||
hooksEnabledForStopFailure &&
|
||||
hookSystem &&
|
||||
this.config.hasHooksForEvent?.('StopFailure')
|
||||
) {
|
||||
// Fire-and-forget: don't wait for hook to complete
|
||||
hookSystem
|
||||
.fireStopFailureEvent(errorType, errorMessage)
|
||||
.catch((err) => {
|
||||
debugLogger.warn(`StopFailure hook failed: ${err}`);
|
||||
});
|
||||
|
||||
const hookSystem = this.config.getHookSystem?.();
|
||||
const hooksEnabledForStopFailure =
|
||||
!this.config.getDisableAllHooks?.();
|
||||
if (
|
||||
hooksEnabledForStopFailure &&
|
||||
hookSystem &&
|
||||
this.config.hasHooksForEvent?.('StopFailure')
|
||||
) {
|
||||
// Fire-and-forget: don't wait for hook to complete
|
||||
hookSystem
|
||||
.fireStopFailureEvent(errorType, errorMessage)
|
||||
.catch((err) => {
|
||||
debugLogger.warn(`StopFailure hook failed: ${err}`);
|
||||
});
|
||||
}
|
||||
|
||||
if (errorStatus === 429) {
|
||||
throw new RequestError(
|
||||
429,
|
||||
'Rate limit exceeded. Try again later.',
|
||||
);
|
||||
}
|
||||
|
||||
throw error;
|
||||
}
|
||||
|
||||
if (usageMetadata) {
|
||||
this.#recordPromptTokenCount(usageMetadata);
|
||||
// Kick off rewrite in background (non-blocking, runs parallel to tools)
|
||||
if (this.messageRewriter) {
|
||||
this.messageRewriter.flushTurn(pendingSend.signal);
|
||||
}
|
||||
|
||||
const durationMs = Date.now() - streamStartTime;
|
||||
await this.messageEmitter.emitUsageMetadata(
|
||||
usageMetadata,
|
||||
'',
|
||||
durationMs,
|
||||
);
|
||||
}
|
||||
|
||||
if (functionCalls.length > 0) {
|
||||
const toolResponseParts = await this.runToolCalls(
|
||||
pendingSend.signal,
|
||||
promptId,
|
||||
functionCalls,
|
||||
);
|
||||
nextMessage = { role: 'user', parts: toolResponseParts };
|
||||
}
|
||||
}
|
||||
|
||||
// Wait for any pending rewrite before returning
|
||||
if (errorStatus === 429) {
|
||||
throw new RequestError(
|
||||
429,
|
||||
'Rate limit exceeded. Try again later.',
|
||||
);
|
||||
}
|
||||
|
||||
throw error;
|
||||
}
|
||||
|
||||
if (usageMetadata) {
|
||||
this.#recordPromptTokenCount(usageMetadata);
|
||||
// Kick off rewrite in background (non-blocking, runs parallel to tools)
|
||||
if (this.messageRewriter) {
|
||||
await this.messageRewriter.waitForPendingRewrites();
|
||||
this.messageRewriter.flushTurn(pendingSend.signal);
|
||||
}
|
||||
|
||||
// Fire Stop hook loop (aligned with core path in client.ts)
|
||||
// This is triggered after model response completes with no pending tool calls
|
||||
return this.#handleStopHookLoop(
|
||||
pendingSend,
|
||||
promptId,
|
||||
hooksEnabled,
|
||||
messageBus,
|
||||
const durationMs = Date.now() - streamStartTime;
|
||||
await this.messageEmitter.emitUsageMetadata(
|
||||
usageMetadata,
|
||||
'',
|
||||
durationMs,
|
||||
);
|
||||
},
|
||||
(result) => (result.stopReason === 'cancelled' ? 'cancelled' : 'ok'),
|
||||
}
|
||||
|
||||
if (functionCalls.length > 0) {
|
||||
const toolResponseParts = await this.runToolCalls(
|
||||
pendingSend.signal,
|
||||
promptId,
|
||||
functionCalls,
|
||||
);
|
||||
nextMessage = { role: 'user', parts: toolResponseParts };
|
||||
}
|
||||
}
|
||||
|
||||
// Wait for any pending rewrite before returning
|
||||
if (this.messageRewriter) {
|
||||
await this.messageRewriter.waitForPendingRewrites();
|
||||
}
|
||||
|
||||
// Fire Stop hook loop (aligned with core path in client.ts)
|
||||
// This is triggered after model response completes with no pending tool calls
|
||||
return this.#handleStopHookLoop(
|
||||
pendingSend,
|
||||
promptId,
|
||||
hooksEnabled,
|
||||
messageBus,
|
||||
);
|
||||
},
|
||||
);
|
||||
@ -1039,16 +895,10 @@ export class Session implements SessionContext {
|
||||
return { stopReason: 'end_turn' };
|
||||
}
|
||||
|
||||
// Get response text from the chat history
|
||||
const history = this.#getCurrentChat().getHistory();
|
||||
const lastModelMessage = history
|
||||
.filter((msg: Content) => msg.role === 'model')
|
||||
.pop();
|
||||
// Extract last model text without cloning the full history.
|
||||
const responseText =
|
||||
lastModelMessage?.parts
|
||||
?.filter((p: Part): p is { text: string } & Part => 'text' in p)
|
||||
.map((p: { text: string }) => p.text)
|
||||
.join('') || '[no response text]';
|
||||
this.#getCurrentChat().getLastModelMessageText?.() ||
|
||||
'[no response text]';
|
||||
|
||||
const response = await messageBus.request<
|
||||
HookExecutionRequest,
|
||||
@ -1746,34 +1596,8 @@ export class Session implements SessionContext {
|
||||
yolo: ApprovalMode.YOLO,
|
||||
};
|
||||
|
||||
// `modeId` arrives over the wire (ACP `session/set_mode`, or
|
||||
// `setSessionConfigOption` casting an unknown `value` to string), so
|
||||
// validate at this boundary. An unknown id would otherwise call
|
||||
// `setApprovalMode(undefined)` — leaving the permission system in an
|
||||
// undefined state — and the A2 broadcast below would fan the bogus id
|
||||
// out to every attached SSE client.
|
||||
const approvalMode = modeMap[params.modeId as ApprovalModeValue];
|
||||
if (approvalMode === undefined) {
|
||||
throw RequestError.invalidParams(
|
||||
undefined,
|
||||
`Unknown approval mode: ${params.modeId}`,
|
||||
);
|
||||
}
|
||||
this.config.setApprovalMode(approvalMode);
|
||||
|
||||
// A2 (#4511): notify attached clients of an in-session mode switch.
|
||||
// Mirrors the model-update extNotification in `setModel`.
|
||||
void this.client
|
||||
.extNotification('qwen/notify/session/mode-update', {
|
||||
v: 1,
|
||||
sessionId: this.sessionId,
|
||||
currentModeId: params.modeId,
|
||||
})
|
||||
.catch((error) => {
|
||||
// Advisory only; a failed notification must not fail the mode
|
||||
// switch. Matches the model-update extNotification in `setModel`.
|
||||
debugLogger.debug('mode-update extNotification failed', error);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
@ -1810,27 +1634,6 @@ export class Session implements SessionContext {
|
||||
: undefined,
|
||||
);
|
||||
|
||||
// A1 (#4511): notify attached clients of an in-session model switch so a
|
||||
// `/model` slash command or plan-mode change reaches the bus (today only
|
||||
// the HTTP `POST /session/:id/model` path publishes `model_switched`).
|
||||
// `current_model_update` is NOT an ACP `SessionUpdate` variant (the type
|
||||
// is the external @agentclientprotocol/sdk union, which has
|
||||
// `current_mode_update` but not a model equivalent), so this goes over
|
||||
// the agent→bridge `extNotification` side-channel. The bridge demuxes it
|
||||
// to `model_switched` and SUPPRESSES it when the bridge itself is driving
|
||||
// the change (the HTTP path also flows through this method), avoiding a
|
||||
// double publish. Fire-and-forget, matching the MCP-budget extNotification.
|
||||
void this.client
|
||||
.extNotification('qwen/notify/session/model-update', {
|
||||
v: 1,
|
||||
sessionId: this.sessionId,
|
||||
currentModelId: parsed.modelId,
|
||||
})
|
||||
.catch((error) => {
|
||||
// Advisory only; a failed notification must not fail the model switch.
|
||||
debugLogger.debug('model-update extNotification failed', error);
|
||||
});
|
||||
|
||||
if (options.persistDefault ?? true) {
|
||||
const persistScope = getPersistScopeForModelSelection(this.settings);
|
||||
this.settings.setValue(persistScope, 'model.name', parsed.modelId);
|
||||
@ -1872,29 +1675,6 @@ export class Session implements SessionContext {
|
||||
};
|
||||
|
||||
await this.sendUpdate(update);
|
||||
|
||||
// A2 (#4511): promote the mode change to the bridge side-channel so
|
||||
// it reaches `approval_mode_changed` on the SSE bus, matching the
|
||||
// extNotification in `setMode`.
|
||||
//
|
||||
// Unlike `setMode`, this path already published the legacy
|
||||
// `session_update{current_mode_update}` frame via `sendUpdate` above
|
||||
// (BridgeClient.sessionUpdate fans it onto the bus). Tell the demux to
|
||||
// skip its compat dual-emit so the IDE companion sees exactly one
|
||||
// legacy frame for this change, not two. `setMode` omits the flag, so
|
||||
// its dual-emit still fires (it has no `sendUpdate`).
|
||||
void this.client
|
||||
.extNotification('qwen/notify/session/mode-update', {
|
||||
v: 1,
|
||||
sessionId: this.sessionId,
|
||||
currentModeId: newModeId,
|
||||
legacyFrameSent: true,
|
||||
})
|
||||
.catch((error) => {
|
||||
// Advisory only; a failed notification must not fail the mode
|
||||
// change. Matches the model-update extNotification in `setModel`.
|
||||
debugLogger.debug('mode-update extNotification failed', error);
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
|
||||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||||
import { ToolCallEmitter } from './ToolCallEmitter.js';
|
||||
import type { SessionContext, SubagentMeta } from '../types.js';
|
||||
import type { SessionContext } from '../types.js';
|
||||
import type {
|
||||
Config,
|
||||
ToolRegistry,
|
||||
@ -77,7 +77,7 @@ describe('ToolCallEmitter', () => {
|
||||
locations: [],
|
||||
kind: 'other',
|
||||
rawInput: { arg1: 'value1' },
|
||||
_meta: { toolName: 'unknown_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'unknown_tool' },
|
||||
});
|
||||
});
|
||||
|
||||
@ -101,7 +101,7 @@ describe('ToolCallEmitter', () => {
|
||||
locations: [{ path: '/test/file.ts', line: 10 }],
|
||||
kind: 'edit',
|
||||
rawInput: { path: '/test.ts' },
|
||||
_meta: { toolName: 'edit_file', provenance: 'builtin' },
|
||||
_meta: { toolName: 'edit_file' },
|
||||
});
|
||||
});
|
||||
|
||||
@ -125,7 +125,7 @@ describe('ToolCallEmitter', () => {
|
||||
expect(sendUpdateSpy).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
rawInput: {},
|
||||
_meta: { toolName: 'test_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'test_tool' },
|
||||
}),
|
||||
);
|
||||
});
|
||||
@ -153,7 +153,7 @@ describe('ToolCallEmitter', () => {
|
||||
locations: [], // Fallback to empty
|
||||
kind: 'other', // Fallback to other
|
||||
rawInput: { invalid: true },
|
||||
_meta: { toolName: 'failing_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'failing_tool' },
|
||||
});
|
||||
});
|
||||
});
|
||||
@ -174,7 +174,7 @@ describe('ToolCallEmitter', () => {
|
||||
toolCallId: 'call-123',
|
||||
status: 'completed',
|
||||
rawOutput: 'Tool completed successfully',
|
||||
_meta: { toolName: 'test_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'test_tool' },
|
||||
}),
|
||||
);
|
||||
});
|
||||
@ -198,7 +198,7 @@ describe('ToolCallEmitter', () => {
|
||||
content: { type: 'text', text: 'Something went wrong' },
|
||||
},
|
||||
],
|
||||
_meta: { toolName: 'test_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'test_tool' },
|
||||
});
|
||||
});
|
||||
|
||||
@ -228,7 +228,7 @@ describe('ToolCallEmitter', () => {
|
||||
newText: 'new content',
|
||||
},
|
||||
],
|
||||
_meta: { toolName: 'edit_file', provenance: 'builtin' },
|
||||
_meta: { toolName: 'edit_file' },
|
||||
}),
|
||||
);
|
||||
});
|
||||
@ -263,7 +263,7 @@ describe('ToolCallEmitter', () => {
|
||||
},
|
||||
},
|
||||
],
|
||||
_meta: { toolName: 'edit_file', provenance: 'builtin' },
|
||||
_meta: { toolName: 'edit_file' },
|
||||
}),
|
||||
);
|
||||
});
|
||||
@ -289,7 +289,7 @@ describe('ToolCallEmitter', () => {
|
||||
},
|
||||
],
|
||||
rawOutput: 'raw output',
|
||||
_meta: { toolName: 'test_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'test_tool' },
|
||||
}),
|
||||
);
|
||||
});
|
||||
@ -307,7 +307,7 @@ describe('ToolCallEmitter', () => {
|
||||
toolCallId: 'call-empty',
|
||||
status: 'completed',
|
||||
content: [],
|
||||
_meta: { toolName: 'test_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'test_tool' },
|
||||
});
|
||||
});
|
||||
|
||||
@ -399,7 +399,7 @@ describe('ToolCallEmitter', () => {
|
||||
content: { type: 'text', text: 'Connection timeout' },
|
||||
},
|
||||
],
|
||||
_meta: { toolName: 'test_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'test_tool' },
|
||||
});
|
||||
});
|
||||
});
|
||||
@ -543,7 +543,7 @@ describe('ToolCallEmitter', () => {
|
||||
},
|
||||
],
|
||||
rawOutput: { unknownField: 'value', nested: { data: 123 } },
|
||||
_meta: { toolName: 'test_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'test_tool' },
|
||||
}),
|
||||
);
|
||||
});
|
||||
@ -565,7 +565,7 @@ describe('ToolCallEmitter', () => {
|
||||
toolCallId: 'call-extra',
|
||||
status: 'completed',
|
||||
rawOutput: 'Result text',
|
||||
_meta: { toolName: 'test_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'test_tool' },
|
||||
}),
|
||||
);
|
||||
});
|
||||
@ -580,10 +580,7 @@ describe('ToolCallEmitter', () => {
|
||||
|
||||
const call = sendUpdateSpy.mock.calls[0][0];
|
||||
expect(call.rawOutput).toBeUndefined();
|
||||
expect(call._meta).toEqual({
|
||||
toolName: 'test_tool',
|
||||
provenance: 'builtin',
|
||||
});
|
||||
expect(call._meta).toEqual({ toolName: 'test_tool' });
|
||||
});
|
||||
});
|
||||
|
||||
@ -674,7 +671,7 @@ describe('ToolCallEmitter', () => {
|
||||
content: { type: 'text', text: 'Text content from message' },
|
||||
},
|
||||
],
|
||||
_meta: { toolName: 'test_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'test_tool' },
|
||||
});
|
||||
});
|
||||
|
||||
@ -706,121 +703,10 @@ describe('ToolCallEmitter', () => {
|
||||
},
|
||||
],
|
||||
rawOutput: 'raw result',
|
||||
_meta: { toolName: 'test_tool', provenance: 'builtin' },
|
||||
_meta: { toolName: 'test_tool' },
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('resolveToolProvenance (#4175 F4 prereq, chiga0 #19 P0)', () => {
|
||||
// Pure static utility — exercise without an emitter instance.
|
||||
it('classifies a plain tool name as builtin (no serverId)', () => {
|
||||
const out = ToolCallEmitter.resolveToolProvenance('shell');
|
||||
expect(out).toEqual({ provenance: 'builtin' });
|
||||
});
|
||||
|
||||
it('classifies a tool name without mcp__ prefix as builtin', () => {
|
||||
const out = ToolCallEmitter.resolveToolProvenance('read_file');
|
||||
expect(out).toEqual({ provenance: 'builtin' });
|
||||
});
|
||||
|
||||
it('classifies mcp__<server>__<tool> as mcp with serverId', () => {
|
||||
const out = ToolCallEmitter.resolveToolProvenance(
|
||||
'mcp__filesystem__read',
|
||||
);
|
||||
expect(out).toEqual({ provenance: 'mcp', serverId: 'filesystem' });
|
||||
});
|
||||
|
||||
it('preserves underscores in the tool segment', () => {
|
||||
// Server segment is `playwright`; tool segment is `take_screenshot`
|
||||
// (with underscore inside the tool name — `split("__")` handles
|
||||
// this because we split on the double-underscore delimiter).
|
||||
const out = ToolCallEmitter.resolveToolProvenance(
|
||||
'mcp__playwright__take_screenshot',
|
||||
);
|
||||
expect(out).toEqual({ provenance: 'mcp', serverId: 'playwright' });
|
||||
});
|
||||
|
||||
it('classifies malformed mcp__ prefix (only one segment) as builtin', () => {
|
||||
// No double-underscore delimiter past the prefix → not a valid
|
||||
// mcp tool name; fall back to builtin rather than stamping
|
||||
// garbage serverId.
|
||||
const out = ToolCallEmitter.resolveToolProvenance('mcp__just_one');
|
||||
expect(out).toEqual({ provenance: 'builtin' });
|
||||
});
|
||||
|
||||
it('classifies mcp__<empty>__<tool> as builtin (empty server segment)', () => {
|
||||
const out = ToolCallEmitter.resolveToolProvenance('mcp____read');
|
||||
expect(out).toEqual({ provenance: 'builtin' });
|
||||
});
|
||||
|
||||
it('classifies any tool as subagent when subagentMeta is present', () => {
|
||||
// subagent takes precedence over mcp__ naming — a sub-agent
|
||||
// calling an MCP tool is rendered as "subagent block" not
|
||||
// "MCP block" in the UI.
|
||||
const out = ToolCallEmitter.resolveToolProvenance('mcp__fs__read', {
|
||||
agentType: 'researcher',
|
||||
} as unknown as SubagentMeta);
|
||||
expect(out).toEqual({ provenance: 'subagent' });
|
||||
});
|
||||
|
||||
it('classifies a plain builtin tool with subagentMeta as subagent', () => {
|
||||
const out = ToolCallEmitter.resolveToolProvenance('shell', {
|
||||
agentType: 'coder',
|
||||
} as unknown as SubagentMeta);
|
||||
expect(out).toEqual({ provenance: 'subagent' });
|
||||
});
|
||||
});
|
||||
|
||||
describe('provenance stamping on emit (#4175 F4 prereq)', () => {
|
||||
it('stamps provenance:mcp + serverId on emitStart for mcp__ tools', async () => {
|
||||
await emitter.emitStart({
|
||||
toolName: 'mcp__github__create_issue',
|
||||
callId: 'call-mcp',
|
||||
args: { title: 'bug' },
|
||||
});
|
||||
expect(sendUpdateSpy).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
sessionUpdate: 'tool_call',
|
||||
_meta: expect.objectContaining({
|
||||
toolName: 'mcp__github__create_issue',
|
||||
provenance: 'mcp',
|
||||
serverId: 'github',
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('stamps provenance:subagent (no serverId) when subagentMeta present', async () => {
|
||||
await emitter.emitStart({
|
||||
toolName: 'shell',
|
||||
callId: 'call-sub',
|
||||
args: {},
|
||||
subagentMeta: { agentType: 'researcher' } as unknown as SubagentMeta,
|
||||
});
|
||||
const call = sendUpdateSpy.mock.calls[0][0];
|
||||
expect(call._meta.provenance).toBe('subagent');
|
||||
expect(call._meta.serverId).toBeUndefined();
|
||||
});
|
||||
|
||||
it('stamps provenance on emitResult so reconnecting clients can re-derive it', async () => {
|
||||
await emitter.emitResult({
|
||||
toolName: 'mcp__db__query',
|
||||
callId: 'call-r',
|
||||
success: true,
|
||||
message: [],
|
||||
});
|
||||
const call = sendUpdateSpy.mock.calls[0][0];
|
||||
expect(call._meta.provenance).toBe('mcp');
|
||||
expect(call._meta.serverId).toBe('db');
|
||||
});
|
||||
|
||||
it('stamps provenance on emitError as well', async () => {
|
||||
await emitter.emitError('call-e', 'mcp__fs__write', new Error('boom'));
|
||||
const call = sendUpdateSpy.mock.calls[0][0];
|
||||
expect(call._meta.provenance).toBe('mcp');
|
||||
expect(call._meta.serverId).toBe('fs');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@ -57,10 +57,6 @@ export class ToolCallEmitter extends BaseEmitter {
|
||||
params.toolName,
|
||||
params.args,
|
||||
);
|
||||
const provenance = ToolCallEmitter.resolveToolProvenance(
|
||||
params.toolName,
|
||||
params.subagentMeta,
|
||||
);
|
||||
|
||||
await this.sendUpdate({
|
||||
sessionUpdate: 'tool_call',
|
||||
@ -74,8 +70,6 @@ export class ToolCallEmitter extends BaseEmitter {
|
||||
_meta: {
|
||||
toolName: params.toolName,
|
||||
...params.subagentMeta,
|
||||
provenance: provenance.provenance,
|
||||
...(provenance.serverId ? { serverId: provenance.serverId } : {}),
|
||||
...(BaseEmitter.toEpochMs(params.timestamp) != null && {
|
||||
timestamp: BaseEmitter.toEpochMs(params.timestamp),
|
||||
}),
|
||||
@ -130,10 +124,6 @@ export class ToolCallEmitter extends BaseEmitter {
|
||||
}
|
||||
|
||||
// Build the update
|
||||
const provenance = ToolCallEmitter.resolveToolProvenance(
|
||||
params.toolName,
|
||||
params.subagentMeta,
|
||||
);
|
||||
const update: Parameters<typeof this.sendUpdate>[0] = {
|
||||
sessionUpdate: 'tool_call_update',
|
||||
toolCallId: params.callId,
|
||||
@ -142,8 +132,6 @@ export class ToolCallEmitter extends BaseEmitter {
|
||||
_meta: {
|
||||
toolName: params.toolName,
|
||||
...params.subagentMeta,
|
||||
provenance: provenance.provenance,
|
||||
...(provenance.serverId ? { serverId: provenance.serverId } : {}),
|
||||
...(BaseEmitter.toEpochMs(params.timestamp) != null && {
|
||||
timestamp: BaseEmitter.toEpochMs(params.timestamp),
|
||||
}),
|
||||
@ -173,10 +161,6 @@ export class ToolCallEmitter extends BaseEmitter {
|
||||
error: Error,
|
||||
subagentMeta?: SubagentMeta,
|
||||
): Promise<void> {
|
||||
const provenance = ToolCallEmitter.resolveToolProvenance(
|
||||
toolName,
|
||||
subagentMeta,
|
||||
);
|
||||
await this.sendUpdate({
|
||||
sessionUpdate: 'tool_call_update',
|
||||
toolCallId: callId,
|
||||
@ -187,55 +171,10 @@ export class ToolCallEmitter extends BaseEmitter {
|
||||
_meta: {
|
||||
toolName,
|
||||
...subagentMeta,
|
||||
provenance: provenance.provenance,
|
||||
...(provenance.serverId ? { serverId: provenance.serverId } : {}),
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a tool's provenance for UI dispatch on tool_call events
|
||||
* (#4175 F4 prereq, chiga0 issue #19 P0). The SDK reads `_meta.
|
||||
* provenance` + `_meta.serverId` to render builtin / MCP-server-badge /
|
||||
* subagent-block differently. Without this stamping, the SDK falls
|
||||
* back to string-matching the toolName which can't reliably
|
||||
* distinguish builtin from subagent.
|
||||
*
|
||||
* Resolution rules:
|
||||
* - `subagentMeta` present → `'subagent'` (a Task tool / Codex
|
||||
* subagent / etc. wrapping its own tool calls)
|
||||
* - toolName matches `mcp__<server>__<tool>` → `'mcp'` with
|
||||
* `serverId: <server>`. Naming convention from
|
||||
* `packages/core/src/tools/mcp-tool.ts` in the
|
||||
* `@qwen-code/qwen-code-core` package — mirrors the SDK's same
|
||||
* heuristic fallback so SDK consumers stay consistent with
|
||||
* daemon classification.
|
||||
* - everything else → `'builtin'`
|
||||
*
|
||||
* Static + pure so it can be unit-tested without an emitter
|
||||
* instance. Exported via `ToolCallEmitter.resolveToolProvenance`.
|
||||
*/
|
||||
static resolveToolProvenance(
|
||||
toolName: string,
|
||||
subagentMeta?: SubagentMeta,
|
||||
): { provenance: 'builtin' | 'mcp' | 'subagent'; serverId?: string } {
|
||||
if (subagentMeta !== undefined) {
|
||||
return { provenance: 'subagent' };
|
||||
}
|
||||
if (toolName.startsWith('mcp__')) {
|
||||
// mcp__<serverName>__<toolName> — split is "__", not single "_",
|
||||
// so server / tool segments can contain underscores. Require
|
||||
// both a non-empty server segment and at least one segment past
|
||||
// it; malformed names fall through to 'builtin' rather than
|
||||
// stamping an empty/garbage serverId.
|
||||
const parts = toolName.split('__');
|
||||
if (parts.length >= 3 && parts[1] && parts[1].length > 0) {
|
||||
return { provenance: 'mcp', serverId: parts[1] };
|
||||
}
|
||||
}
|
||||
return { provenance: 'builtin' };
|
||||
}
|
||||
|
||||
// ==================== Public Utilities ====================
|
||||
|
||||
/**
|
||||
|
||||
@ -1,129 +0,0 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2026 Qwen Team
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import {
|
||||
buildBackgroundEntryLabel,
|
||||
type AgentTask,
|
||||
type Config,
|
||||
type MonitorTask,
|
||||
type ShellTask,
|
||||
} from '@qwen-code/qwen-code-core';
|
||||
import {
|
||||
STATUS_SCHEMA_VERSION,
|
||||
type ServeSessionAgentTaskStatus,
|
||||
type ServeSessionMonitorTaskStatus,
|
||||
type ServeSessionShellTaskStatus,
|
||||
type ServeSessionTaskStatus,
|
||||
type ServeSessionTasksStatus,
|
||||
} from '../../serve/status.js';
|
||||
|
||||
function runtimeMs(
|
||||
entry: { startTime: number; endTime?: number },
|
||||
now: number,
|
||||
) {
|
||||
return Math.max(0, (entry.endTime ?? now) - entry.startTime);
|
||||
}
|
||||
|
||||
function serializeAgentTask(
|
||||
entry: AgentTask,
|
||||
now: number,
|
||||
): ServeSessionAgentTaskStatus {
|
||||
return {
|
||||
kind: 'agent',
|
||||
id: entry.id,
|
||||
label: buildBackgroundEntryLabel(entry),
|
||||
description: entry.description,
|
||||
status: entry.status,
|
||||
startTime: entry.startTime,
|
||||
runtimeMs: runtimeMs(entry, now),
|
||||
outputFile: entry.outputFile,
|
||||
...(entry.endTime !== undefined ? { endTime: entry.endTime } : {}),
|
||||
...(entry.subagentType !== undefined
|
||||
? { subagentType: entry.subagentType }
|
||||
: {}),
|
||||
isBackgrounded: entry.isBackgrounded,
|
||||
...(entry.error !== undefined ? { error: entry.error } : {}),
|
||||
...(entry.resumeBlockedReason !== undefined
|
||||
? { resumeBlockedReason: entry.resumeBlockedReason }
|
||||
: {}),
|
||||
};
|
||||
}
|
||||
|
||||
function serializeShellTask(
|
||||
entry: ShellTask,
|
||||
now: number,
|
||||
): ServeSessionShellTaskStatus {
|
||||
return {
|
||||
kind: 'shell',
|
||||
id: entry.id,
|
||||
label: entry.command,
|
||||
description: entry.description,
|
||||
status: entry.status,
|
||||
startTime: entry.startTime,
|
||||
runtimeMs: runtimeMs(entry, now),
|
||||
outputFile: entry.outputFile,
|
||||
command: entry.command,
|
||||
cwd: entry.cwd,
|
||||
...(entry.endTime !== undefined ? { endTime: entry.endTime } : {}),
|
||||
...(entry.pid !== undefined ? { pid: entry.pid } : {}),
|
||||
...(entry.exitCode !== undefined ? { exitCode: entry.exitCode } : {}),
|
||||
...(entry.error !== undefined ? { error: entry.error } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
function serializeMonitorTask(
|
||||
entry: MonitorTask,
|
||||
now: number,
|
||||
): ServeSessionMonitorTaskStatus {
|
||||
return {
|
||||
kind: 'monitor',
|
||||
id: entry.id,
|
||||
label: entry.description,
|
||||
description: entry.description,
|
||||
status: entry.status,
|
||||
startTime: entry.startTime,
|
||||
runtimeMs: runtimeMs(entry, now),
|
||||
command: entry.command,
|
||||
eventCount: entry.eventCount,
|
||||
lastEventTime: entry.lastEventTime,
|
||||
droppedLines: entry.droppedLines,
|
||||
...(entry.endTime !== undefined ? { endTime: entry.endTime } : {}),
|
||||
...(entry.pid !== undefined ? { pid: entry.pid } : {}),
|
||||
...(entry.exitCode !== undefined ? { exitCode: entry.exitCode } : {}),
|
||||
...(entry.error !== undefined ? { error: entry.error } : {}),
|
||||
...(entry.ownerAgentId !== undefined
|
||||
? { ownerAgentId: entry.ownerAgentId }
|
||||
: {}),
|
||||
};
|
||||
}
|
||||
|
||||
export function buildSessionTasksStatus(
|
||||
sessionId: string,
|
||||
config: Config,
|
||||
now = Date.now(),
|
||||
): ServeSessionTasksStatus {
|
||||
const tasks: ServeSessionTaskStatus[] = [
|
||||
...config
|
||||
.getBackgroundTaskRegistry()
|
||||
.getAll()
|
||||
.map((entry) => serializeAgentTask(entry, now)),
|
||||
...config
|
||||
.getBackgroundShellRegistry()
|
||||
.getAll()
|
||||
.map((entry) => serializeShellTask(entry, now)),
|
||||
...config
|
||||
.getMonitorRegistry()
|
||||
.getAll()
|
||||
.map((entry) => serializeMonitorTask(entry, now)),
|
||||
].sort((a, b) => a.startTime - b.startTime);
|
||||
|
||||
return {
|
||||
v: STATUS_SCHEMA_VERSION,
|
||||
sessionId,
|
||||
now,
|
||||
tasks,
|
||||
};
|
||||
}
|
||||
@ -13,11 +13,16 @@ const mockExtensionManagerInstance = {
|
||||
refreshCache: mockRefreshCache,
|
||||
};
|
||||
|
||||
vi.mock('@qwen-code/qwen-code-core', () => ({
|
||||
ExtensionManager: vi
|
||||
.fn()
|
||||
.mockImplementation(() => mockExtensionManagerInstance),
|
||||
}));
|
||||
vi.mock('@qwen-code/qwen-code-core', async (importOriginal) => {
|
||||
const actual =
|
||||
await importOriginal<typeof import('@qwen-code/qwen-code-core')>();
|
||||
return {
|
||||
...actual,
|
||||
ExtensionManager: vi
|
||||
.fn()
|
||||
.mockImplementation(() => mockExtensionManagerInstance),
|
||||
};
|
||||
});
|
||||
|
||||
vi.mock('../../config/settings.js', () => ({
|
||||
loadSettings: vi.fn().mockReturnValue({
|
||||
@ -132,4 +137,26 @@ describe('extensionToOutputString', () => {
|
||||
|
||||
expect(resultWithoutInline).toEqual(resultWithInlineFalse);
|
||||
});
|
||||
|
||||
it('should redact URL credentials in install source output', () => {
|
||||
const extension = createMockExtension({
|
||||
installMetadata: {
|
||||
type: 'git',
|
||||
source: 'https://user:token@example.com/owner/repo.git',
|
||||
},
|
||||
});
|
||||
|
||||
const result = extensionToOutputString(
|
||||
extension,
|
||||
mockExtensionManager,
|
||||
'/workspace',
|
||||
true,
|
||||
);
|
||||
|
||||
expect(result).toContain(
|
||||
'https://***REDACTED***@example.com/owner/repo.git',
|
||||
);
|
||||
expect(result).not.toContain('user');
|
||||
expect(result).not.toContain('token');
|
||||
});
|
||||
});
|
||||
|
||||
@ -4,7 +4,11 @@
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import { ExtensionManager, type Extension } from '@qwen-code/qwen-code-core';
|
||||
import {
|
||||
ExtensionManager,
|
||||
redactUrlCredentials,
|
||||
type Extension,
|
||||
} from '@qwen-code/qwen-code-core';
|
||||
import { loadSettings } from '../../config/settings.js';
|
||||
import {
|
||||
requestConsentOrFail,
|
||||
@ -51,7 +55,7 @@ export function extensionToOutputString(
|
||||
let output = `${inline ? '' : status} ${extension.config.name} (${extension.config.version})`;
|
||||
output += `\n ${t('Path:')} ${extension.path}`;
|
||||
if (extension.installMetadata) {
|
||||
output += `\n ${t('Source:')} ${extension.installMetadata.source} (${t('Type:')} ${extension.installMetadata.type})`;
|
||||
output += `\n ${t('Source:')} ${redactUrlCredentials(extension.installMetadata.source)} (${t('Type:')} ${extension.installMetadata.type})`;
|
||||
if (extension.installMetadata.ref) {
|
||||
output += `\n ${t('Ref:')} ${extension.installMetadata.ref}`;
|
||||
}
|
||||
|
||||
@ -12,7 +12,12 @@ import type { Argv, CommandModule } from 'yargs';
|
||||
// handler below so it only loads when the user actually runs `qwen serve`.
|
||||
import { writeStderrLine } from '../utils/stdioHelpers.js';
|
||||
import { DEFAULT_RING_SIZE } from '../serve/eventBus.js';
|
||||
import { MCP_BUDGET_WARN_FRACTION } from '@qwen-code/qwen-code-core';
|
||||
import {
|
||||
ApprovalMode,
|
||||
MCP_BUDGET_WARN_FRACTION,
|
||||
} from '@qwen-code/qwen-code-core';
|
||||
import { loadSettings } from '../config/settings.js';
|
||||
import { HEADLESS_YOLO_NO_SANDBOX_WARNING } from '../utils/headlessSafetyWarnings.js';
|
||||
|
||||
/**
|
||||
* Pause the current async function indefinitely. Used after the daemon
|
||||
@ -41,9 +46,6 @@ interface ServeArgs {
|
||||
'http-bridge': boolean;
|
||||
'mcp-client-budget'?: number;
|
||||
'mcp-budget-mode'?: 'enforce' | 'warn' | 'off';
|
||||
'allow-origin'?: string[];
|
||||
'prompt-deadline-ms'?: number;
|
||||
'writer-idle-timeout-ms'?: number;
|
||||
}
|
||||
|
||||
export const serveCommand: CommandModule<unknown, ServeArgs> = {
|
||||
@ -147,24 +149,6 @@ export const serveCommand: CommandModule<unknown, ServeArgs> = {
|
||||
'refused (`disabledReason: "budget"`, deterministic by mcpServers ' +
|
||||
'declaration order). `off`: pure observability. Boot rejects ' +
|
||||
'`enforce` without a budget.',
|
||||
})
|
||||
.option('allow-origin', {
|
||||
type: 'string',
|
||||
array: true,
|
||||
description:
|
||||
'T2.4 (#4514). Cross-origin allowlist for browser webui clients.',
|
||||
})
|
||||
.option('prompt-deadline-ms', {
|
||||
type: 'number',
|
||||
description:
|
||||
'T2.9 (#4514). Server-side wallclock cap on POST /session/:id/prompt (ms). ' +
|
||||
'Falls back to QWEN_SERVE_PROMPT_DEADLINE_MS. Positive integer.',
|
||||
})
|
||||
.option('writer-idle-timeout-ms', {
|
||||
type: 'number',
|
||||
description:
|
||||
'T2.9 (#4514). Per-SSE-connection idle deadline (ms). ' +
|
||||
'Falls back to QWEN_SERVE_WRITER_IDLE_TIMEOUT_MS. Positive integer.',
|
||||
}) as unknown as Argv<ServeArgs>,
|
||||
handler: async (argv) => {
|
||||
if (!argv['http-bridge']) {
|
||||
@ -224,6 +208,37 @@ export const serveCommand: CommandModule<unknown, ServeArgs> = {
|
||||
);
|
||||
}
|
||||
|
||||
// Emit the headless-YOLO safety warning at daemon startup if
|
||||
// settings.json statically configures yolo + no sandbox. We can't
|
||||
// use `getHeadlessYoloSafetyWarning(config)` here because the daemon
|
||||
// hasn't constructed a `Config` yet — sessions get their own — so
|
||||
// we re-derive the predicate from the same settings.json the
|
||||
// sessions will load. Per-session override (the ACP client flipping
|
||||
// approval mode mid-session) is out of scope here; this warns about
|
||||
// a deployment that's wide-open at boot. Suppress with
|
||||
// QWEN_CODE_SUPPRESS_YOLO_WARNING=1.
|
||||
try {
|
||||
const loaded = loadSettings(argv.workspace ?? process.cwd());
|
||||
const merged = loaded.merged;
|
||||
const approvalMode = merged.tools?.approvalMode;
|
||||
const sandbox = merged.tools?.sandbox;
|
||||
const sandboxEnv = process.env['SANDBOX'];
|
||||
const suppress = process.env['QWEN_CODE_SUPPRESS_YOLO_WARNING'];
|
||||
const suppressed = suppress === '1' || suppress === 'true';
|
||||
if (
|
||||
approvalMode === ApprovalMode.YOLO &&
|
||||
!sandbox &&
|
||||
!sandboxEnv &&
|
||||
!suppressed
|
||||
) {
|
||||
writeStderrLine(HEADLESS_YOLO_NO_SANDBOX_WARNING);
|
||||
}
|
||||
} catch {
|
||||
// Settings load can fail (corrupt JSON, etc.); don't block
|
||||
// daemon startup just to emit a warning — the existing settings
|
||||
// path will report the same error to the user via Session.
|
||||
}
|
||||
|
||||
// Lazy-load the serve module so non-serve invocations don't pay for
|
||||
// express + body-parser + qs in their startup path.
|
||||
const { runQwenServe } = await import('../serve/index.js');
|
||||
@ -240,15 +255,6 @@ export const serveCommand: CommandModule<unknown, ServeArgs> = {
|
||||
requireAuth: argv['require-auth'],
|
||||
mcpClientBudget,
|
||||
mcpBudgetMode: resolvedMcpMode,
|
||||
...(argv['allow-origin'] && argv['allow-origin'].length > 0
|
||||
? { allowOrigins: argv['allow-origin'] }
|
||||
: {}),
|
||||
...(argv['prompt-deadline-ms'] !== undefined
|
||||
? { promptDeadlineMs: argv['prompt-deadline-ms'] }
|
||||
: {}),
|
||||
...(argv['writer-idle-timeout-ms'] !== undefined
|
||||
? { writerIdleTimeoutMs: argv['writer-idle-timeout-ms'] }
|
||||
: {}),
|
||||
});
|
||||
} catch (err) {
|
||||
writeStderrLine(
|
||||
|
||||
@ -36,7 +36,6 @@ import {
|
||||
} from '@qwen-code/qwen-code-core';
|
||||
import { extensionsCommand } from '../commands/extensions.js';
|
||||
import { hooksCommand } from '../commands/hooks.js';
|
||||
import { normalizeDisabledToolList } from './normalizeDisabledTools.js';
|
||||
import type { Settings } from './settings.js';
|
||||
import { loadSettings, SettingScope } from './settings.js';
|
||||
import {
|
||||
@ -76,6 +75,11 @@ export function isValidSessionId(value: string): boolean {
|
||||
|
||||
import { isWorkspaceTrusted } from './trustedFolders.js';
|
||||
import { writeStderrLine } from '../utils/stdioHelpers.js';
|
||||
import {
|
||||
parseDurationSeconds,
|
||||
validateMaxToolCalls,
|
||||
validateMaxWallTimeSetting,
|
||||
} from '../utils/runBudget.js';
|
||||
|
||||
const debugLogger = createDebugLogger('CONFIG');
|
||||
|
||||
@ -183,6 +187,8 @@ export interface CliArgs {
|
||||
*/
|
||||
worktree?: string | undefined;
|
||||
maxSessionTurns: number | undefined;
|
||||
maxWallTime: string | undefined;
|
||||
maxToolCalls: number | undefined;
|
||||
coreTools: string[] | undefined;
|
||||
excludeTools: string[] | undefined;
|
||||
disabledSlashCommands: string[] | undefined;
|
||||
@ -848,6 +854,16 @@ export async function parseArguments(): Promise<CliArgs> {
|
||||
type: 'number',
|
||||
description: 'Maximum number of session turns',
|
||||
})
|
||||
.option('max-wall-time', {
|
||||
type: 'string',
|
||||
description:
|
||||
'Run-level wall-clock budget for headless / unattended runs. Accepts seconds (e.g. `90`), or a duration string with unit (e.g. `30s`, `5m`, `1h`, `1.5h`). Minimum 1s — sub-second values (`500ms`, `0.5`) are rejected as typos; max ~24 days. Aborts the run with exit code 55 when exceeded.',
|
||||
})
|
||||
.option('max-tool-calls', {
|
||||
type: 'number',
|
||||
description:
|
||||
'Maximum cumulative tool calls executed during the run (success or failure; `structured_output` under --json-schema is exempt). Aborts with exit code 55 when exceeded. -1 / unset means no limit; 0 means "no tool calls allowed" (first call aborts). Capped at 1,000,000 to catch typos.',
|
||||
})
|
||||
.option('core-tools', {
|
||||
type: 'array',
|
||||
string: true,
|
||||
@ -1136,6 +1152,65 @@ export async function loadHierarchicalGeminiMemory(
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolves the wall-clock budget for a run. Returns seconds (`-1` =
|
||||
* unlimited). Order of precedence: `--max-wall-time` flag, then
|
||||
* `model.maxWallTimeSeconds` from settings, else unlimited.
|
||||
*
|
||||
* The CLI flag is a duration string (`30s` / `5m` / `1h` / `90`); the
|
||||
* settings entry is a plain number of seconds (parity with
|
||||
* `model.maxSessionTurns`). Both layers reject `0` and out-of-range
|
||||
* values up front — a typo in a CI guardrail should fail loud at startup,
|
||||
* not silently disable the budget.
|
||||
*/
|
||||
function resolveMaxWallTimeSeconds(argv: CliArgs, settings: Settings): number {
|
||||
if (argv.maxWallTime !== undefined && argv.maxWallTime !== null) {
|
||||
try {
|
||||
return parseDurationSeconds(String(argv.maxWallTime));
|
||||
} catch (err) {
|
||||
throw new Error(`--max-wall-time: ${(err as Error).message}`);
|
||||
}
|
||||
}
|
||||
const fromSettings = settings.model?.maxWallTimeSeconds;
|
||||
if (typeof fromSettings === 'number') {
|
||||
try {
|
||||
return validateMaxWallTimeSetting(fromSettings);
|
||||
} catch (err) {
|
||||
throw new Error(`settings.json: ${(err as Error).message}`);
|
||||
}
|
||||
}
|
||||
return -1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolves the tool-call budget for a run. Returns the validated count
|
||||
* (`-1` = unlimited). Order of precedence: `--max-tool-calls` flag, then
|
||||
* `model.maxToolCalls` from settings, else unlimited.
|
||||
*
|
||||
* Symmetric with `resolveMaxWallTimeSeconds`: yargs accepts `NaN` from
|
||||
* non-numeric flag values, and the enforcer's `>= 0` gate would silently
|
||||
* disable the budget for `NaN` / negatives. Validate up front so a typo
|
||||
* in a CI guardrail fails loudly.
|
||||
*/
|
||||
function resolveMaxToolCalls(argv: CliArgs, settings: Settings): number {
|
||||
if (argv.maxToolCalls !== undefined && argv.maxToolCalls !== null) {
|
||||
try {
|
||||
return validateMaxToolCalls(argv.maxToolCalls);
|
||||
} catch (err) {
|
||||
throw new Error(`--max-tool-calls: ${(err as Error).message}`);
|
||||
}
|
||||
}
|
||||
const fromSettings = settings.model?.maxToolCalls;
|
||||
if (typeof fromSettings === 'number') {
|
||||
try {
|
||||
return validateMaxToolCalls(fromSettings);
|
||||
} catch (err) {
|
||||
throw new Error(`settings.json: ${(err as Error).message}`);
|
||||
}
|
||||
}
|
||||
return -1;
|
||||
}
|
||||
|
||||
export function isDebugMode(argv: CliArgs): boolean {
|
||||
return (
|
||||
argv.debug ||
|
||||
@ -1445,10 +1520,16 @@ export async function loadCliConfig(
|
||||
// Resolve the per-workspace tool denylist (#4175 Wave 4 PR 17). De-duplicate
|
||||
// while preserving original casing; downstream lookups go through
|
||||
// `Config.getDisabledTools()` which materializes a Set, so the order here
|
||||
// is only meaningful for diagnostic output. Shared helper since the MCP
|
||||
// restart refresh path (`cli/src/acp-integration/acpAgent.ts`) MUST agree
|
||||
// byte-for-byte with this — #4175 F1 (#4319) fold-in for #4329.
|
||||
const disabledTools = normalizeDisabledToolList(settings.tools?.disabled);
|
||||
// is only meaningful for diagnostic output.
|
||||
const disabledTools: string[] = [];
|
||||
const seenDisabledTools = new Set<string>();
|
||||
for (const raw of settings.tools?.disabled ?? []) {
|
||||
if (typeof raw !== 'string') continue;
|
||||
const trimmed = raw.trim();
|
||||
if (!trimmed || seenDisabledTools.has(trimmed)) continue;
|
||||
seenDisabledTools.add(trimmed);
|
||||
disabledTools.push(trimmed);
|
||||
}
|
||||
|
||||
// Helper: check if a tool is explicitly covered by an allow rule OR by the
|
||||
// coreTools whitelist. Uses alias matching for coreTools (via isToolEnabled)
|
||||
@ -1724,6 +1805,7 @@ export async function loadCliConfig(
|
||||
screenReader,
|
||||
},
|
||||
telemetry: telemetrySettings,
|
||||
outboundCorrelation: settings.outboundCorrelation,
|
||||
usageStatisticsEnabled: settings.privacy?.usageStatisticsEnabled ?? true,
|
||||
clearContextOnIdle: settings.context?.clearContextOnIdle,
|
||||
fileFiltering: settings.context?.fileFiltering,
|
||||
@ -1745,6 +1827,8 @@ export async function loadCliConfig(
|
||||
sessionTokenLimit: settings.model?.sessionTokenLimit ?? -1,
|
||||
maxSessionTurns:
|
||||
argv.maxSessionTurns ?? settings.model?.maxSessionTurns ?? -1,
|
||||
maxWallTimeSeconds: resolveMaxWallTimeSeconds(argv, settings),
|
||||
maxToolCalls: resolveMaxToolCalls(argv, settings),
|
||||
experimentalZedIntegration: argv.acp || argv.experimentalAcp || false,
|
||||
cronEnabled: settings.experimental?.cron ?? false,
|
||||
computerUseEnabled: settings.tools?.computerUse?.enabled ?? true,
|
||||
|
||||
@ -1,119 +0,0 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2025 Qwen Team
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { normalizeDisabledToolList } from './normalizeDisabledTools.js';
|
||||
|
||||
describe('normalizeDisabledToolList', () => {
|
||||
describe('non-array short-circuit', () => {
|
||||
it('returns [] for undefined', () => {
|
||||
expect(normalizeDisabledToolList(undefined)).toEqual([]);
|
||||
});
|
||||
it('returns [] for null', () => {
|
||||
expect(normalizeDisabledToolList(null)).toEqual([]);
|
||||
});
|
||||
it('returns [] for a plain object', () => {
|
||||
expect(normalizeDisabledToolList({ 0: 'Foo' })).toEqual([]);
|
||||
});
|
||||
it('returns [] for a number', () => {
|
||||
expect(normalizeDisabledToolList(42)).toEqual([]);
|
||||
});
|
||||
it('returns [] for a string', () => {
|
||||
expect(normalizeDisabledToolList('Foo')).toEqual([]);
|
||||
});
|
||||
it('returns [] for a boolean', () => {
|
||||
expect(normalizeDisabledToolList(true)).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('typeof-string filter', () => {
|
||||
it('drops non-string entries individually without aborting', () => {
|
||||
expect(
|
||||
normalizeDisabledToolList([
|
||||
42,
|
||||
'Foo',
|
||||
null,
|
||||
'Bar',
|
||||
{ name: 'Baz' },
|
||||
true,
|
||||
'Qux',
|
||||
]),
|
||||
).toEqual(['Foo', 'Bar', 'Qux']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('trim + empty-skip', () => {
|
||||
it('trims surrounding whitespace', () => {
|
||||
expect(normalizeDisabledToolList([' Foo ', '\tBar\n'])).toEqual([
|
||||
'Foo',
|
||||
'Bar',
|
||||
]);
|
||||
});
|
||||
it('drops empty-after-trim entries', () => {
|
||||
expect(normalizeDisabledToolList(['', ' ', '\t', '\n', 'Foo'])).toEqual([
|
||||
'Foo',
|
||||
]);
|
||||
});
|
||||
it('returns [] when every entry is whitespace-only', () => {
|
||||
expect(normalizeDisabledToolList(['', ' ', '\t', '\n'])).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('dedupe', () => {
|
||||
it('removes exact duplicates, preserving first-occurrence order', () => {
|
||||
expect(normalizeDisabledToolList(['Foo', 'Bar', 'Foo', 'Baz'])).toEqual([
|
||||
'Foo',
|
||||
'Bar',
|
||||
'Baz',
|
||||
]);
|
||||
});
|
||||
it('dedupes after trim — whitespace variants collapse', () => {
|
||||
expect(normalizeDisabledToolList(['Foo', ' Foo', 'Foo '])).toEqual([
|
||||
'Foo',
|
||||
]);
|
||||
});
|
||||
it('does NOT case-fold — `Foo` and `foo` stay distinct', () => {
|
||||
expect(normalizeDisabledToolList(['Foo', 'foo', 'FOO'])).toEqual([
|
||||
'Foo',
|
||||
'foo',
|
||||
'FOO',
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('boot/restart parity scenarios (BkwQW class — wenshao #4329)', () => {
|
||||
it("['Foo', ' Foo ', ''] → ['Foo'] (the bug that the helper was extracted to prevent)", () => {
|
||||
// Pre-extraction, this scenario was handled at boot (config.ts) but
|
||||
// the MCP restart path (acpAgent.ts) had only typeof-string filter.
|
||||
// After fold-in, both call sites share this helper so a hand-edited
|
||||
// `tools.disabled: [' Foo ']` produces Set(['Foo']) at boot AND
|
||||
// after every subsequent MCP restart.
|
||||
expect(normalizeDisabledToolList(['Foo', ' Foo ', ''])).toEqual([
|
||||
'Foo',
|
||||
]);
|
||||
});
|
||||
|
||||
it('mixed real-world settings — typo + extra whitespace + dup', () => {
|
||||
expect(
|
||||
normalizeDisabledToolList([
|
||||
'ShellTool',
|
||||
'WebFetch',
|
||||
' ShellTool', // typo: extra space
|
||||
'', // operator pressed Enter
|
||||
'WebFetch ', // trailing whitespace
|
||||
]),
|
||||
).toEqual(['ShellTool', 'WebFetch']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('order preservation', () => {
|
||||
it('first-occurrence order survives dedupe + trim', () => {
|
||||
expect(
|
||||
normalizeDisabledToolList(['Zebra', 'Apple', ' Zebra', 'Banana']),
|
||||
).toEqual(['Zebra', 'Apple', 'Banana']);
|
||||
});
|
||||
});
|
||||
});
|
||||
@ -1,63 +0,0 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2025 Qwen Team
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* Normalize a raw `tools.disabled` settings array into the canonical
|
||||
* deduplicated list the agent / restart paths share.
|
||||
*
|
||||
* Boot path (`cli/src/config/config.ts`'s `disabledTools` array
|
||||
* construction) and MCP restart refresh path
|
||||
* (`cli/src/acp-integration/acpAgent.ts` post-`restartMcpServer`
|
||||
* settings refresh) must agree byte-for-byte on what counts as
|
||||
* "disabled" — without that agreement, `ToolRegistry.has(tool.name)`
|
||||
* exact-match check silently re-registers tools whose disabled-name
|
||||
* carries whitespace (e.g., `' Foo '` typed in settings.json by hand).
|
||||
*
|
||||
* Lifted from the two inline implementations in #4175 F1 (#4319)
|
||||
* — extraction closes wenshao review thread + #4329. Behavior is
|
||||
* byte-identical to both pre-extraction loops; tests cover the
|
||||
* scenarios the inline code was specifically written to handle
|
||||
* (typeof string filter, trim, drop empty, dedupe) plus the
|
||||
* non-array short-circuit (acpAgent.ts had it via `Array.isArray`
|
||||
* gate; config.ts didn't because settings type already constrains
|
||||
* the field — but exposing it as a defensive guard makes the
|
||||
* helper safe to call with any user-controlled value).
|
||||
*
|
||||
* Behavior contract:
|
||||
*
|
||||
* 1. Non-array `raw` (object / number / boolean / null / undefined)
|
||||
* → return `[]`.
|
||||
* 2. Non-string entries inside the array → skipped individually
|
||||
* (does NOT abort the whole list — e.g., `[42, 'Foo', null]` → `['Foo']`).
|
||||
* 3. Each string entry is `.trim()`-ed.
|
||||
* 4. Empty-after-trim entries (`''`, `' '`, `'\n'`, `'\t'`) → skipped.
|
||||
* 5. Duplicates de-duped, preserving first-occurrence order.
|
||||
* Downstream callers materialize the result to `Set<string>`
|
||||
* so order is only meaningful for diagnostic output today,
|
||||
* but this helper preserves it for any future order-sensitive
|
||||
* consumer.
|
||||
*
|
||||
* The helper does NOT case-fold (e.g., `'Foo'` vs `'foo'` remain
|
||||
* distinct) — Stage 1 tool names are case-sensitive throughout
|
||||
* `ToolRegistry`, so case-folding here would silently break tool
|
||||
* lookups elsewhere. Unicode normalization (`String.prototype.normalize`)
|
||||
* is similarly out of scope; if a user pastes a combining-form vs
|
||||
* precomposed-form variant they want collapsed, that's a separate
|
||||
* decision tracked under workspace settings UX.
|
||||
*/
|
||||
export function normalizeDisabledToolList(raw: unknown): string[] {
|
||||
if (!Array.isArray(raw)) return [];
|
||||
const out: string[] = [];
|
||||
const seen = new Set<string>();
|
||||
for (const entry of raw) {
|
||||
if (typeof entry !== 'string') continue;
|
||||
const trimmed = entry.trim();
|
||||
if (!trimmed || seen.has(trimmed)) continue;
|
||||
seen.add(trimmed);
|
||||
out.push(trimmed);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
@ -3109,6 +3109,122 @@ describe('Settings Loading and Merging', () => {
|
||||
externallyModifiedUserSettingsContent.modelProviders.openai,
|
||||
);
|
||||
});
|
||||
|
||||
it('persists removed MCP servers when replacing the top-level mcpServers object', () => {
|
||||
(mockFsExistsSync as Mock).mockReturnValue(true);
|
||||
|
||||
const userSettingsContent = {
|
||||
[SETTINGS_VERSION_KEY]: SETTINGS_VERSION,
|
||||
ui: {
|
||||
theme: 'dark',
|
||||
},
|
||||
mcpServers: {
|
||||
keep: {
|
||||
command: 'node',
|
||||
},
|
||||
remove: {
|
||||
command: 'python',
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
let currentUserSettingsContent = JSON.stringify(userSettingsContent);
|
||||
|
||||
(fs.readFileSync as Mock).mockImplementation(
|
||||
(p: fs.PathOrFileDescriptor) => {
|
||||
if (p === USER_SETTINGS_PATH) {
|
||||
return currentUserSettingsContent;
|
||||
}
|
||||
return '{}';
|
||||
},
|
||||
);
|
||||
|
||||
const settings = loadSettings(MOCK_WORKSPACE_DIR);
|
||||
currentUserSettingsContent = JSON.stringify(userSettingsContent);
|
||||
|
||||
settings.setValue(SettingScope.User, 'mcpServers', {
|
||||
keep: {
|
||||
command: 'node',
|
||||
},
|
||||
});
|
||||
|
||||
const writeCall = (fs.writeFileSync as Mock).mock.calls.at(-1);
|
||||
expect(writeCall).toBeDefined();
|
||||
|
||||
const writtenContent = JSON.parse(String(writeCall?.[1]));
|
||||
expect(writtenContent.ui).toEqual({ theme: 'dark' });
|
||||
expect(writtenContent.mcpServers).toEqual({
|
||||
keep: {
|
||||
command: 'node',
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('preserves sibling keys for non-MCP top-level object updates', () => {
|
||||
(mockFsExistsSync as Mock).mockReturnValue(true);
|
||||
|
||||
const userSettingsContent = {
|
||||
[SETTINGS_VERSION_KEY]: SETTINGS_VERSION,
|
||||
tools: {
|
||||
approvalMode: 'default',
|
||||
disabled: ['shell'],
|
||||
},
|
||||
};
|
||||
|
||||
let currentUserSettingsContent = JSON.stringify(userSettingsContent);
|
||||
|
||||
(fs.readFileSync as Mock).mockImplementation(
|
||||
(p: fs.PathOrFileDescriptor) => {
|
||||
if (p === USER_SETTINGS_PATH) {
|
||||
return currentUserSettingsContent;
|
||||
}
|
||||
return '{}';
|
||||
},
|
||||
);
|
||||
|
||||
const settings = loadSettings(MOCK_WORKSPACE_DIR);
|
||||
currentUserSettingsContent = JSON.stringify(userSettingsContent);
|
||||
|
||||
settings.setValue(SettingScope.User, 'tools', {
|
||||
disabled: ['read-file'],
|
||||
});
|
||||
|
||||
const writeCall = (fs.writeFileSync as Mock).mock.calls.at(-1);
|
||||
expect(writeCall).toBeDefined();
|
||||
|
||||
const writtenContent = JSON.parse(String(writeCall?.[1]));
|
||||
expect(writtenContent.tools).toEqual({
|
||||
approvalMode: 'default',
|
||||
disabled: ['read-file'],
|
||||
});
|
||||
});
|
||||
|
||||
it('logs when setValue persistence is refused', () => {
|
||||
(mockFsExistsSync as Mock).mockReturnValue(true);
|
||||
(fs.readFileSync as Mock).mockImplementation(
|
||||
(p: fs.PathOrFileDescriptor) => {
|
||||
if (p === USER_SETTINGS_PATH) {
|
||||
return JSON.stringify({
|
||||
[SETTINGS_VERSION_KEY]: SETTINGS_VERSION,
|
||||
});
|
||||
}
|
||||
return '{}';
|
||||
},
|
||||
);
|
||||
|
||||
const settings = loadSettings(MOCK_WORKSPACE_DIR);
|
||||
const mockFn =
|
||||
commentJsonUtils.updateSettingsFilePreservingFormat as Mock;
|
||||
mockFn.mockReturnValueOnce(false);
|
||||
|
||||
settings.setValue(SettingScope.User, 'mcpServers', {});
|
||||
|
||||
expect(mockDebugLogger.error).toHaveBeenCalledWith(
|
||||
expect.stringContaining(
|
||||
'saveSettings: updateSettingsFilePreservingFormat returned false',
|
||||
),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('loadEnvironment', () => {
|
||||
|
||||
@ -468,7 +468,8 @@ export class LoadedSettings {
|
||||
setNestedPropertySafe(settingsFile.settings, key, value);
|
||||
setNestedPropertySafe(settingsFile.originalSettings, key, value);
|
||||
this._merged = this.computeMergedSettings();
|
||||
saveSettings(settingsFile, createSettingsUpdate(key, value));
|
||||
const replacePath = key === 'mcpServers' ? key.split('.') : [];
|
||||
saveSettings(settingsFile, createSettingsUpdate(key, value), replacePath);
|
||||
}
|
||||
|
||||
recomputeMerged(): void {
|
||||
@ -1281,6 +1282,7 @@ export function saveSettings(
|
||||
string,
|
||||
unknown
|
||||
>,
|
||||
replacePath: readonly string[] = [],
|
||||
): void {
|
||||
try {
|
||||
// Ensure the directory exists
|
||||
@ -1290,7 +1292,17 @@ export function saveSettings(
|
||||
}
|
||||
|
||||
// Use the format-preserving update function
|
||||
updateSettingsFilePreservingFormat(settingsFile.path, updates);
|
||||
const written = updateSettingsFilePreservingFormat(
|
||||
settingsFile.path,
|
||||
updates,
|
||||
false,
|
||||
replacePath,
|
||||
);
|
||||
if (!written) {
|
||||
debugLogger.error(
|
||||
`saveSettings: updateSettingsFilePreservingFormat returned false for ${settingsFile.path}`,
|
||||
);
|
||||
}
|
||||
} catch (error) {
|
||||
debugLogger.error('Error saving user settings file.');
|
||||
debugLogger.error(error instanceof Error ? error.message : String(error));
|
||||
|
||||
@ -8,6 +8,7 @@ import type {
|
||||
MCPServerConfig,
|
||||
BugCommandSettings,
|
||||
TelemetrySettings,
|
||||
OutboundCorrelationSettings,
|
||||
AuthType,
|
||||
ChatCompressionSettings,
|
||||
ModelProvidersConfig,
|
||||
@ -1037,6 +1038,29 @@ const SETTINGS_SCHEMA = {
|
||||
},
|
||||
},
|
||||
|
||||
outboundCorrelation: {
|
||||
type: 'object',
|
||||
label: 'Outbound Correlation',
|
||||
category: 'Advanced',
|
||||
requiresRestart: true,
|
||||
default: undefined as OutboundCorrelationSettings | undefined,
|
||||
description:
|
||||
"SECURITY-RELEVANT. Controls what client-side correlation data qwen-code writes into outbound LLM API requests (DashScope, OpenAI, Anthropic, etc.) — separate from `telemetry.*` which governs data flow into the operator's OWN OTLP collector. All values default to off. Opt in only when the LLM provider also reports into your OTel collector for cross-process trace stitching (e.g. ARMS Tracing + DashScope).",
|
||||
showInDialog: false,
|
||||
jsonSchemaOverride: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
propagateTraceContext: {
|
||||
description:
|
||||
"Requires `telemetry.enabled: true`. Inject W3C `traceparent` header on outbound `fetch` requests (LLM SDK calls, MCP StreamableHTTP, WebFetch, ...). Default: false — trace context stays internal to the operator's OTLP collector and is NOT written onto third-party request streams. Set true only when you want cross-process trace stitching with an OTel-aware LLM provider (e.g. ARMS+DashScope). Client HTTP spans are still emitted in either case; this flag only governs the wire `traceparent` header.",
|
||||
type: 'boolean',
|
||||
default: false,
|
||||
},
|
||||
},
|
||||
additionalProperties: false,
|
||||
},
|
||||
},
|
||||
|
||||
fastModel: {
|
||||
type: 'string',
|
||||
label: 'Fast Model',
|
||||
@ -1076,6 +1100,26 @@ const SETTINGS_SCHEMA = {
|
||||
'Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.',
|
||||
showInDialog: false,
|
||||
},
|
||||
maxWallTimeSeconds: {
|
||||
type: 'number',
|
||||
label: 'Max Wall-Clock Time (seconds)',
|
||||
category: 'Model',
|
||||
requiresRestart: false,
|
||||
default: -1,
|
||||
description:
|
||||
'Run-level wall-clock budget for headless / unattended runs, in seconds. -1 means unlimited; otherwise must be in [1, ~2,147,483] (sub-second values and values above ~24 days are rejected as typos). Overridable per-invocation via --max-wall-time (which also accepts duration suffixes like 5m, 1.5h).',
|
||||
showInDialog: false,
|
||||
},
|
||||
maxToolCalls: {
|
||||
type: 'number',
|
||||
label: 'Max Tool Calls',
|
||||
category: 'Model',
|
||||
requiresRestart: false,
|
||||
default: -1,
|
||||
description:
|
||||
'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" (first call aborts). Capped at 1,000,000 to catch typos. Overridable via --max-tool-calls.',
|
||||
showInDialog: false,
|
||||
},
|
||||
chatCompression: {
|
||||
type: 'object',
|
||||
label: 'Chat Compression',
|
||||
@ -1109,7 +1153,8 @@ const SETTINGS_SCHEMA = {
|
||||
category: 'Model',
|
||||
requiresRestart: false,
|
||||
default: true,
|
||||
description: 'Disable all loop detection checks (streaming and LLM).',
|
||||
description:
|
||||
'Skip streaming loop detection. Defaults to true to avoid false-positive interruptions; set to false to re-enable as an unattended-run guardrail.',
|
||||
showInDialog: false,
|
||||
},
|
||||
skipStartupContext: {
|
||||
@ -1787,82 +1832,6 @@ const SETTINGS_SCHEMA = {
|
||||
},
|
||||
},
|
||||
|
||||
policy: {
|
||||
type: 'object',
|
||||
label: 'Daemon Policy',
|
||||
category: 'Daemon',
|
||||
requiresRestart: true,
|
||||
default: {},
|
||||
description:
|
||||
'Daemon multi-client coordination policies. Tool-level allow/deny rules ' +
|
||||
'live under `permissions`; this section is for runtime mediation behavior ' +
|
||||
'between concurrent HTTP clients sharing one `qwen serve` daemon.',
|
||||
showInDialog: false,
|
||||
properties: {
|
||||
permissionStrategy: {
|
||||
type: 'enum',
|
||||
label: 'Permission Mediation Policy',
|
||||
category: 'Daemon',
|
||||
requiresRestart: true,
|
||||
default: 'first-responder',
|
||||
description:
|
||||
'How permission requests resolve when multiple clients are attached. ' +
|
||||
'`first-responder` (default) = any client decides, first wins. ' +
|
||||
'`designated` = only the prompt originator decides; falls back to ' +
|
||||
'first-responder if originator is anonymous. ' +
|
||||
'NOTE: client identity comes from self-declared X-Qwen-Client-Id ' +
|
||||
'with no proof-of-possession (pair-token mechanism is a future PR), ' +
|
||||
'so any client observing originatorClientId on SSE frames can ' +
|
||||
'register with the same id and impersonate the originator. ' +
|
||||
'`consensus` = N-of-M voters must agree. Default N=floor(M/2)+1, ' +
|
||||
'which means UNANIMITY for M=2 (quorum=2, both must agree) and ' +
|
||||
'supermajority for larger even M (M=4 → quorum=3; M=6 → quorum=4). ' +
|
||||
'For M=2 specifically, split votes resolve only via permissionTimeoutMs. ' +
|
||||
'`local-only` = only loopback clients can RESOLVE; remote clients ' +
|
||||
'can still ABORT a pending permission via the cancel sentinel ' +
|
||||
'({outcome:"cancelled"}) — F3 v1 keeps cancel cross-policy for ' +
|
||||
'consistency. Strict-cancel-too deployments need a dedicated ' +
|
||||
'loopback-bound daemon. ' +
|
||||
'Requires daemon restart — F3 v1 reads this once at boot.',
|
||||
showInDialog: true,
|
||||
options: [
|
||||
{ value: 'first-responder', label: 'First Responder' },
|
||||
{ value: 'designated', label: 'Designated Originator' },
|
||||
{ value: 'consensus', label: 'Consensus Quorum' },
|
||||
{ value: 'local-only', label: 'Local Only' },
|
||||
],
|
||||
},
|
||||
consensusQuorum: {
|
||||
type: 'number',
|
||||
label: 'Consensus Quorum Override',
|
||||
category: 'Daemon',
|
||||
requiresRestart: true,
|
||||
default: undefined as number | undefined,
|
||||
description:
|
||||
'Optional fixed quorum size for consensus policy. Capped at M ' +
|
||||
'(count of registered voters at request issue time) to prevent ' +
|
||||
'unreachable quorum. Unset = floor(M/2)+1. ' +
|
||||
'Requires daemon restart — F3 v1 reads this once at boot.',
|
||||
showInDialog: false,
|
||||
// Wenshao review #4335 / 3271185604 — runQwenServe.ts validates
|
||||
// `Number.isInteger(n) && n >= 1` and refuses to boot otherwise.
|
||||
// Override the generated schema so IDE inline validation
|
||||
// (VSCode, JetBrains via JSON Schema) flags `0`, `-1`, `1.5`
|
||||
// BEFORE the user restarts the daemon. The bare `type:'number'`
|
||||
// mapping accepts all of these.
|
||||
jsonSchemaOverride: {
|
||||
type: 'integer',
|
||||
minimum: 1,
|
||||
description:
|
||||
'Optional fixed quorum size for consensus policy. Capped at M ' +
|
||||
'(count of registered voters at request issue time) to prevent ' +
|
||||
'unreachable quorum. Unset = floor(M/2)+1. ' +
|
||||
'Requires daemon restart — F3 v1 reads this once at boot.',
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
mcp: {
|
||||
type: 'object',
|
||||
label: 'MCP',
|
||||
|
||||
@ -24,7 +24,7 @@ import type { CliArgs } from './config/config.js';
|
||||
import { type LoadedSettings } from './config/settings.js';
|
||||
import { appEvents, AppEvent } from './utils/events.js';
|
||||
import type { Config } from '@qwen-code/qwen-code-core';
|
||||
import { OutputFormat } from '@qwen-code/qwen-code-core';
|
||||
import { ApprovalMode, OutputFormat } from '@qwen-code/qwen-code-core';
|
||||
|
||||
const mockWriteStderrLine = vi.hoisted(() => vi.fn());
|
||||
|
||||
@ -181,6 +181,7 @@ describe('gemini.tsx main function', () => {
|
||||
isInteractive: () => false,
|
||||
getQuestion: () => '',
|
||||
getSandbox: () => false,
|
||||
getApprovalMode: () => ApprovalMode.DEFAULT,
|
||||
getDebugMode: () => false,
|
||||
getListExtensions: () => false,
|
||||
getMcpServers: () => ({}),
|
||||
@ -260,6 +261,7 @@ describe('gemini.tsx main function', () => {
|
||||
isInteractive: () => false,
|
||||
getQuestion: () => 'bare prompt',
|
||||
getSandbox: () => false,
|
||||
getApprovalMode: () => ApprovalMode.DEFAULT,
|
||||
getDebugMode: () => false,
|
||||
getListExtensions: () => false,
|
||||
getMcpServers: () => ({}),
|
||||
@ -569,6 +571,7 @@ describe('gemini.tsx main function', () => {
|
||||
isInteractive: () => false,
|
||||
getQuestion: () => ' hello stream ',
|
||||
getSandbox: () => false,
|
||||
getApprovalMode: () => ApprovalMode.DEFAULT,
|
||||
getDebugMode: () => false,
|
||||
getListExtensions: () => false,
|
||||
getMcpServers: () => ({}),
|
||||
@ -773,6 +776,8 @@ describe('gemini.tsx main function kitty protocol', () => {
|
||||
disabledSlashCommands: undefined,
|
||||
authType: undefined,
|
||||
maxSessionTurns: undefined,
|
||||
maxWallTime: undefined,
|
||||
maxToolCalls: undefined,
|
||||
experimentalLsp: undefined,
|
||||
channel: undefined,
|
||||
chatRecording: undefined,
|
||||
|
||||
@ -86,7 +86,9 @@ import { start_sandbox } from './utils/sandbox.js';
|
||||
import { getStartupWarnings } from './utils/startupWarnings.js';
|
||||
import { getUserStartupWarnings } from './utils/userStartupWarnings.js';
|
||||
import { getCliVersion } from './utils/version.js';
|
||||
import { initializeWarningHandler } from './utils/warningHandler.js';
|
||||
import { writeStderrLine } from './utils/stdioHelpers.js';
|
||||
import { getHeadlessYoloSafetyWarning } from './utils/headlessSafetyWarnings.js';
|
||||
import { computeWindowTitle } from './utils/windowTitle.js';
|
||||
import {
|
||||
startEarlyInputCapture,
|
||||
@ -415,6 +417,7 @@ export async function main() {
|
||||
setStartupEventSink((name, attrs) => recordStartupEvent(name, attrs));
|
||||
}
|
||||
setupUnhandledRejectionHandler();
|
||||
initializeWarningHandler();
|
||||
|
||||
if (process.argv.includes('--bare')) {
|
||||
process.env[QWEN_CODE_SIMPLE_ENV_VAR] = '1';
|
||||
@ -1006,6 +1009,17 @@ export async function main() {
|
||||
}
|
||||
}
|
||||
|
||||
// Headless + YOLO without a sandbox lets the model auto-approve and
|
||||
// execute shell / write / edit tools at the current process's
|
||||
// privilege level. Emit a one-line stderr warning so unattended runs
|
||||
// have at least an observable signal. Interactive runs are excluded
|
||||
// because the user is at the keyboard and the TUI shows approval
|
||||
// state directly. See issue #4103.
|
||||
if (!config.isInteractive()) {
|
||||
const yoloWarning = getHeadlessYoloSafetyWarning(config);
|
||||
if (yoloWarning) writeStderrLine(yoloWarning);
|
||||
}
|
||||
|
||||
// For non-stream-json mode, initialize config here. Stream-json defers
|
||||
// `config.initialize()` to inside `Session.ensureConfigInitialized`
|
||||
// because the initial control_request may register SDK MCP servers
|
||||
|
||||
@ -35,6 +35,7 @@ export interface IControlContext {
|
||||
readonly settings: LoadedSettings;
|
||||
|
||||
permissionMode: PermissionMode;
|
||||
sdkCanUseToolTimeoutMs?: number;
|
||||
sdkMcpServers: Set<string>;
|
||||
mcpClients: Map<string, { client: Client; config: MCPServerConfig }>;
|
||||
inputClosed: boolean;
|
||||
@ -54,6 +55,7 @@ export class ControlContext implements IControlContext {
|
||||
readonly settings: LoadedSettings;
|
||||
|
||||
permissionMode: PermissionMode;
|
||||
sdkCanUseToolTimeoutMs?: number;
|
||||
sdkMcpServers: Set<string>;
|
||||
mcpClients: Map<string, { client: Client; config: MCPServerConfig }>;
|
||||
inputClosed: boolean;
|
||||
|
||||
@ -0,0 +1,186 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2025 Qwen Team
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import {
|
||||
InputFormat,
|
||||
ToolConfirmationOutcome,
|
||||
} from '@qwen-code/qwen-code-core';
|
||||
import { createMinimalSettings } from '../../../config/settings.js';
|
||||
import type { StreamJsonOutputAdapter } from '../../io/StreamJsonOutputAdapter.js';
|
||||
import type { IControlContext } from '../ControlContext.js';
|
||||
import type { IPendingRequestRegistry } from './baseController.js';
|
||||
import { PermissionController } from './permissionController.js';
|
||||
|
||||
function createContext(canUseToolTimeoutMs?: number): IControlContext {
|
||||
const abortController = new AbortController();
|
||||
|
||||
return {
|
||||
config: {
|
||||
getDebugMode: vi.fn().mockReturnValue(false),
|
||||
getInputFormat: vi.fn().mockReturnValue(InputFormat.STREAM_JSON),
|
||||
} as unknown as IControlContext['config'],
|
||||
streamJson: {
|
||||
send: vi.fn(),
|
||||
} as unknown as StreamJsonOutputAdapter,
|
||||
sessionId: 'test-session-id',
|
||||
abortSignal: abortController.signal,
|
||||
debugMode: false,
|
||||
settings: createMinimalSettings(),
|
||||
permissionMode: 'default',
|
||||
sdkCanUseToolTimeoutMs: canUseToolTimeoutMs,
|
||||
sdkMcpServers: new Set<string>(),
|
||||
mcpClients: new Map(),
|
||||
inputClosed: false,
|
||||
};
|
||||
}
|
||||
|
||||
function createRegistry(): IPendingRequestRegistry {
|
||||
return {
|
||||
registerIncomingRequest: vi.fn(),
|
||||
deregisterIncomingRequest: vi.fn(),
|
||||
registerOutgoingRequest: vi.fn(),
|
||||
deregisterOutgoingRequest: vi.fn(),
|
||||
};
|
||||
}
|
||||
|
||||
describe('PermissionController', () => {
|
||||
it('uses SDK canUseTool timeout for outgoing permission requests', async () => {
|
||||
const context = createContext(120_000);
|
||||
const controller = new PermissionController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'PermissionController',
|
||||
);
|
||||
const sendControlRequest = vi
|
||||
.spyOn(controller, 'sendControlRequest')
|
||||
.mockResolvedValue({
|
||||
subtype: 'success',
|
||||
request_id: 'request-1',
|
||||
response: { behavior: 'allow' },
|
||||
});
|
||||
const onConfirm = vi.fn();
|
||||
|
||||
controller.getToolCallUpdateCallback()([
|
||||
{
|
||||
status: 'awaiting_approval',
|
||||
request: {
|
||||
callId: 'tool-call-1',
|
||||
name: 'ask_user_question',
|
||||
args: { questions: [] },
|
||||
},
|
||||
confirmationDetails: {
|
||||
type: 'ask_user_question',
|
||||
title: 'Please answer',
|
||||
onConfirm,
|
||||
},
|
||||
},
|
||||
]);
|
||||
|
||||
await vi.waitFor(() => {
|
||||
expect(sendControlRequest).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
subtype: 'can_use_tool',
|
||||
tool_name: 'ask_user_question',
|
||||
}),
|
||||
120_000,
|
||||
context.abortSignal,
|
||||
);
|
||||
});
|
||||
await vi.waitFor(() => {
|
||||
expect(onConfirm).toHaveBeenCalledWith(
|
||||
ToolConfirmationOutcome.ProceedOnce,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
it('uses default timeout when SDK canUseTool timeout is undefined', async () => {
|
||||
const context = createContext(); // undefined timeout
|
||||
const controller = new PermissionController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'PermissionController',
|
||||
);
|
||||
const sendControlRequest = vi
|
||||
.spyOn(controller, 'sendControlRequest')
|
||||
.mockResolvedValue({
|
||||
subtype: 'success',
|
||||
request_id: 'request-2',
|
||||
response: { behavior: 'allow' },
|
||||
});
|
||||
const onConfirm = vi.fn();
|
||||
|
||||
controller.getToolCallUpdateCallback()([
|
||||
{
|
||||
status: 'awaiting_approval',
|
||||
request: {
|
||||
callId: 'tool-call-2',
|
||||
name: 'ask_user_question',
|
||||
args: { questions: [] },
|
||||
},
|
||||
confirmationDetails: {
|
||||
type: 'ask_user_question',
|
||||
title: 'Please answer',
|
||||
onConfirm,
|
||||
},
|
||||
},
|
||||
]);
|
||||
|
||||
await vi.waitFor(() => {
|
||||
expect(sendControlRequest).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
subtype: 'can_use_tool',
|
||||
tool_name: 'ask_user_question',
|
||||
}),
|
||||
60_000, // DEFAULT_CAN_USE_TOOL_TIMEOUT_MS
|
||||
context.abortSignal,
|
||||
);
|
||||
});
|
||||
await vi.waitFor(() => {
|
||||
expect(onConfirm).toHaveBeenCalledWith(
|
||||
ToolConfirmationOutcome.ProceedOnce,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
it('calls onConfirm with Cancel when sendControlRequest rejects', async () => {
|
||||
const context = createContext(120_000);
|
||||
const controller = new PermissionController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'PermissionController',
|
||||
);
|
||||
vi.spyOn(controller, 'sendControlRequest').mockRejectedValue(
|
||||
new Error('Request timeout'),
|
||||
);
|
||||
const onConfirm = vi.fn();
|
||||
|
||||
controller.getToolCallUpdateCallback()([
|
||||
{
|
||||
status: 'awaiting_approval',
|
||||
request: {
|
||||
callId: 'tool-call-3',
|
||||
name: 'ask_user_question',
|
||||
args: { questions: [] },
|
||||
},
|
||||
confirmationDetails: {
|
||||
type: 'ask_user_question',
|
||||
title: 'Please answer',
|
||||
onConfirm,
|
||||
},
|
||||
},
|
||||
]);
|
||||
|
||||
await vi.waitFor(() => {
|
||||
expect(onConfirm).toHaveBeenCalledWith(
|
||||
ToolConfirmationOutcome.Cancel,
|
||||
expect.objectContaining({
|
||||
cancelMessage: expect.stringContaining('Request timeout'),
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
});
|
||||
@ -36,6 +36,8 @@ import { BaseController } from './baseController.js';
|
||||
// Import ToolCallConfirmationDetails types for type alignment
|
||||
type ToolConfirmationType = 'edit' | 'exec' | 'mcp' | 'info' | 'plan';
|
||||
|
||||
const DEFAULT_CAN_USE_TOOL_TIMEOUT_MS = 60_000;
|
||||
|
||||
export class PermissionController extends BaseController {
|
||||
private pendingOutgoingRequests = new Set<string>();
|
||||
|
||||
@ -427,7 +429,7 @@ export class PermissionController extends BaseController {
|
||||
permission_suggestions: permissionSuggestions,
|
||||
blocked_path: null,
|
||||
} as CLIControlPermissionRequest,
|
||||
undefined, // use default timeout
|
||||
this.context.sdkCanUseToolTimeoutMs ?? DEFAULT_CAN_USE_TOOL_TIMEOUT_MS,
|
||||
this.context.abortSignal,
|
||||
);
|
||||
|
||||
|
||||
@ -0,0 +1,207 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2025 Qwen Team
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import { describe, expect, it, vi } from 'vitest';
|
||||
import { InputFormat } from '@qwen-code/qwen-code-core';
|
||||
import { createMinimalSettings } from '../../../config/settings.js';
|
||||
import type { StreamJsonOutputAdapter } from '../../io/StreamJsonOutputAdapter.js';
|
||||
import type { IControlContext } from '../ControlContext.js';
|
||||
import type { IPendingRequestRegistry } from './baseController.js';
|
||||
import { SystemController } from './systemController.js';
|
||||
|
||||
function createContext(): IControlContext {
|
||||
const abortController = new AbortController();
|
||||
|
||||
return {
|
||||
config: {
|
||||
getDebugMode: vi.fn().mockReturnValue(false),
|
||||
getInputFormat: vi.fn().mockReturnValue(InputFormat.STREAM_JSON),
|
||||
setSdkMode: vi.fn(),
|
||||
getSessionId: vi.fn().mockReturnValue('test-session-id'),
|
||||
addMcpServers: vi.fn(),
|
||||
setSessionSubagents: vi.fn(),
|
||||
setApprovalMode: vi.fn(),
|
||||
setModel: vi.fn(),
|
||||
} as unknown as IControlContext['config'],
|
||||
streamJson: {
|
||||
send: vi.fn(),
|
||||
} as unknown as StreamJsonOutputAdapter,
|
||||
sessionId: 'test-session-id',
|
||||
abortSignal: abortController.signal,
|
||||
debugMode: false,
|
||||
settings: createMinimalSettings(),
|
||||
permissionMode: 'default',
|
||||
sdkCanUseToolTimeoutMs: undefined,
|
||||
sdkMcpServers: new Set<string>(),
|
||||
mcpClients: new Map(),
|
||||
inputClosed: false,
|
||||
};
|
||||
}
|
||||
|
||||
function createRegistry(): IPendingRequestRegistry {
|
||||
return {
|
||||
registerIncomingRequest: vi.fn(),
|
||||
deregisterIncomingRequest: vi.fn(),
|
||||
registerOutgoingRequest: vi.fn(),
|
||||
deregisterOutgoingRequest: vi.fn(),
|
||||
};
|
||||
}
|
||||
|
||||
describe('SystemController', () => {
|
||||
describe('initialize timeout validation', () => {
|
||||
it('accepts valid timeout within bounds', async () => {
|
||||
const context = createContext();
|
||||
const controller = new SystemController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'SystemController',
|
||||
);
|
||||
|
||||
await controller.handleRequest(
|
||||
{
|
||||
subtype: 'initialize',
|
||||
timeout: { canUseTool: 120_000 },
|
||||
},
|
||||
'test-1',
|
||||
);
|
||||
|
||||
expect(context.sdkCanUseToolTimeoutMs).toBe(120_000);
|
||||
});
|
||||
|
||||
it('accepts timeout at maximum boundary (600_000ms)', async () => {
|
||||
const context = createContext();
|
||||
const controller = new SystemController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'SystemController',
|
||||
);
|
||||
|
||||
await controller.handleRequest(
|
||||
{
|
||||
subtype: 'initialize',
|
||||
timeout: { canUseTool: 600_000 },
|
||||
},
|
||||
'test-2',
|
||||
);
|
||||
|
||||
expect(context.sdkCanUseToolTimeoutMs).toBe(600_000);
|
||||
});
|
||||
|
||||
it('ignores timeout exceeding maximum boundary', async () => {
|
||||
const context = createContext();
|
||||
const controller = new SystemController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'SystemController',
|
||||
);
|
||||
|
||||
await controller.handleRequest(
|
||||
{
|
||||
subtype: 'initialize',
|
||||
timeout: { canUseTool: 600_001 },
|
||||
},
|
||||
'test-3',
|
||||
);
|
||||
|
||||
expect(context.sdkCanUseToolTimeoutMs).toBeUndefined();
|
||||
});
|
||||
|
||||
it('ignores Number.MAX_VALUE timeout', async () => {
|
||||
const context = createContext();
|
||||
const controller = new SystemController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'SystemController',
|
||||
);
|
||||
|
||||
await controller.handleRequest(
|
||||
{
|
||||
subtype: 'initialize',
|
||||
timeout: { canUseTool: Number.MAX_VALUE },
|
||||
},
|
||||
'test-4',
|
||||
);
|
||||
|
||||
expect(context.sdkCanUseToolTimeoutMs).toBeUndefined();
|
||||
});
|
||||
|
||||
it('ignores negative timeout', async () => {
|
||||
const context = createContext();
|
||||
const controller = new SystemController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'SystemController',
|
||||
);
|
||||
|
||||
await controller.handleRequest(
|
||||
{
|
||||
subtype: 'initialize',
|
||||
timeout: { canUseTool: -1000 },
|
||||
},
|
||||
'test-5',
|
||||
);
|
||||
|
||||
expect(context.sdkCanUseToolTimeoutMs).toBeUndefined();
|
||||
});
|
||||
|
||||
it('ignores zero timeout', async () => {
|
||||
const context = createContext();
|
||||
const controller = new SystemController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'SystemController',
|
||||
);
|
||||
|
||||
await controller.handleRequest(
|
||||
{
|
||||
subtype: 'initialize',
|
||||
timeout: { canUseTool: 0 },
|
||||
},
|
||||
'test-6',
|
||||
);
|
||||
|
||||
expect(context.sdkCanUseToolTimeoutMs).toBeUndefined();
|
||||
});
|
||||
|
||||
it('ignores Infinity timeout', async () => {
|
||||
const context = createContext();
|
||||
const controller = new SystemController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'SystemController',
|
||||
);
|
||||
|
||||
await controller.handleRequest(
|
||||
{
|
||||
subtype: 'initialize',
|
||||
timeout: { canUseTool: Infinity },
|
||||
},
|
||||
'test-7',
|
||||
);
|
||||
|
||||
expect(context.sdkCanUseToolTimeoutMs).toBeUndefined();
|
||||
});
|
||||
|
||||
it('ignores NaN timeout', async () => {
|
||||
const context = createContext();
|
||||
const controller = new SystemController(
|
||||
context,
|
||||
createRegistry(),
|
||||
'SystemController',
|
||||
);
|
||||
|
||||
await controller.handleRequest(
|
||||
{
|
||||
subtype: 'initialize',
|
||||
timeout: { canUseTool: NaN },
|
||||
},
|
||||
'test-8',
|
||||
);
|
||||
|
||||
expect(context.sdkCanUseToolTimeoutMs).toBeUndefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
@ -31,6 +31,14 @@ import {
|
||||
|
||||
const debugLogger = createDebugLogger('SYSTEM_CONTROLLER');
|
||||
|
||||
/**
|
||||
* Maximum allowed timeout for canUseTool requests (10 minutes).
|
||||
* Node.js setTimeout coerces delays > 2^31-1 to 32-bit signed integers,
|
||||
* which can cause timeouts to fire immediately or never. This cap prevents
|
||||
* such edge cases while still allowing reasonable timeout values.
|
||||
*/
|
||||
const MAX_CAN_USE_TOOL_TIMEOUT_MS = 600_000;
|
||||
|
||||
export class SystemController extends BaseController {
|
||||
/**
|
||||
* Handle system control requests
|
||||
@ -132,6 +140,16 @@ export class SystemController extends BaseController {
|
||||
|
||||
this.context.config.setSdkMode(true);
|
||||
|
||||
const canUseToolTimeout = payload.timeout?.canUseTool;
|
||||
if (
|
||||
typeof canUseToolTimeout === 'number' &&
|
||||
Number.isFinite(canUseToolTimeout) &&
|
||||
canUseToolTimeout > 0 &&
|
||||
canUseToolTimeout <= MAX_CAN_USE_TOOL_TIMEOUT_MS
|
||||
) {
|
||||
this.context.sdkCanUseToolTimeoutMs = canUseToolTimeout;
|
||||
}
|
||||
|
||||
// Process SDK MCP servers
|
||||
if (
|
||||
payload.sdkMcpServers &&
|
||||
|
||||
@ -364,6 +364,9 @@ export interface CLIMcpServerConfig {
|
||||
export interface CLIControlInitializeRequest {
|
||||
subtype: 'initialize';
|
||||
hooks?: HookRegistration[] | null;
|
||||
timeout?: {
|
||||
canUseTool?: number;
|
||||
};
|
||||
/**
|
||||
* SDK MCP servers config
|
||||
* These are MCP servers running in the SDK process, connected via control plane.
|
||||
|
||||
@ -174,6 +174,8 @@ describe('runNonInteractive', () => {
|
||||
getGeminiClient: vi.fn().mockReturnValue(mockGeminiClient),
|
||||
getToolRegistry: vi.fn().mockReturnValue(mockToolRegistry),
|
||||
getMaxSessionTurns: vi.fn().mockReturnValue(10),
|
||||
getMaxWallTimeSeconds: vi.fn().mockReturnValue(-1),
|
||||
getMaxToolCalls: vi.fn().mockReturnValue(-1),
|
||||
getProjectRoot: vi.fn().mockReturnValue('/test/project'),
|
||||
getTargetDir: vi.fn().mockReturnValue('/test/project'),
|
||||
getMcpServers: vi.fn().mockReturnValue(undefined),
|
||||
|
||||
@ -43,7 +43,9 @@ import {
|
||||
handleToolError,
|
||||
handleCancellationError,
|
||||
handleMaxTurnsExceededError,
|
||||
handleBudgetExceededError,
|
||||
} from './utils/errors.js';
|
||||
import { RunBudgetEnforcer } from './utils/runBudget.js';
|
||||
|
||||
const debugLogger = createDebugLogger('NON_INTERACTIVE_CLI');
|
||||
|
||||
@ -220,6 +222,44 @@ export async function runNonInteractive(
|
||||
const geminiClient = config.getGeminiClient();
|
||||
const abortController = options.abortController ?? new AbortController();
|
||||
|
||||
// Run-level budget enforcement for headless / unattended runs
|
||||
// (issue #4103). Tied to the same abortController as user-initiated
|
||||
// SIGINT so the existing cancellation plumbing carries the abort;
|
||||
// `routeAbort` below interprets the reason so the user sees
|
||||
// "budget exceeded" instead of a generic "cancelled" envelope.
|
||||
const budgetEnforcer = new RunBudgetEnforcer(
|
||||
{
|
||||
maxWallTimeSeconds: config.getMaxWallTimeSeconds(),
|
||||
maxToolCalls: config.getMaxToolCalls(),
|
||||
},
|
||||
abortController,
|
||||
);
|
||||
budgetEnforcer.start();
|
||||
|
||||
/**
|
||||
* Called at every abort-detection site in place of
|
||||
* `handleCancellationError` directly. If a budget tripped, surface the
|
||||
* structured budget error (exit 55); otherwise fall through to the
|
||||
* SIGINT / user-cancel path (exit 130) so existing behavior is
|
||||
* preserved. Both branches call into `process.exit(...)` so the
|
||||
* `unreachable` throw is only present to keep the type-checker honest.
|
||||
*/
|
||||
const routeAbort = async (): Promise<never> => {
|
||||
const exceeded = budgetEnforcer.getExceeded();
|
||||
if (exceeded) {
|
||||
await handleBudgetExceededError(config, exceeded);
|
||||
// Explicit unreachable — `handleBudgetExceededError` is `never`
|
||||
// in production (it calls `process.exit`). If a test stubs
|
||||
// `process.exit` or a future refactor makes the handler
|
||||
// resumable, this throw carries the original budget message
|
||||
// so the outer catch's `errorMessage` field stays actionable
|
||||
// (vs. a useless literal "unreachable").
|
||||
throw new Error(exceeded.message);
|
||||
}
|
||||
await handleCancellationError(config);
|
||||
throw new Error('Operation cancelled.');
|
||||
};
|
||||
|
||||
interface LocalQueueItem {
|
||||
displayText: string;
|
||||
modelText: string;
|
||||
@ -628,6 +668,34 @@ export async function runNonInteractive(
|
||||
)
|
||||
: createToolProgressHandler(requestInfo, adapter);
|
||||
|
||||
// Tick BEFORE the call so that --max-tool-calls=N caps the run
|
||||
// at exactly N executions: the (N+1)th tick aborts before the
|
||||
// tool runs. Ticking after would let the (N+1)th tool execute
|
||||
// and only then abort. See issue #4103.
|
||||
//
|
||||
// Exempt `structured_output` ONLY when `--json-schema` is
|
||||
// active: under --json-schema this is the terminal "I'm done"
|
||||
// contract tool, not real work, and counting it would abort
|
||||
// an otherwise-valid completion at the budget edge (budget=3,
|
||||
// model used 3 tools then emits structured_output as call #4
|
||||
// → exit 55 instead of success). Guarding on
|
||||
// `getJsonSchema()` keeps the exemption tied to the feature
|
||||
// that owns the tool name — an MCP server that registers an
|
||||
// unrelated tool literally named `structured_output` would
|
||||
// otherwise inherit a free pass.
|
||||
//
|
||||
// Caveat: failed structured_output calls (Ajv validation
|
||||
// failure) also skip the tick, so a model stuck in a
|
||||
// validation-retry loop is not bounded by --max-tool-calls.
|
||||
// Documented in docs/users/features/headless.md → "Scope".
|
||||
// Combine with --max-session-turns or --max-wall-time.
|
||||
const isStructuredOutputExempt =
|
||||
requestInfo.name === ToolNames.STRUCTURED_OUTPUT &&
|
||||
config.getJsonSchema?.() !== undefined;
|
||||
if (!isStructuredOutputExempt) {
|
||||
budgetEnforcer.tickToolCall();
|
||||
}
|
||||
if (abortController.signal.aborted) await routeAbort();
|
||||
const toolResponse = await executeToolCall(
|
||||
config,
|
||||
requestInfo,
|
||||
@ -764,7 +832,12 @@ export async function runNonInteractive(
|
||||
|
||||
for await (const event of responseStream) {
|
||||
if (abortController.signal.aborted) {
|
||||
await handleCancellationError(config);
|
||||
// Pair the startAssistantMessage() above so stream-json mode
|
||||
// doesn't leave an unterminated message_start when a budget /
|
||||
// SIGINT abort lands mid-stream. Symmetric with the drain-item
|
||||
// loop fix below.
|
||||
adapter.finalizeAssistantMessage();
|
||||
await routeAbort();
|
||||
}
|
||||
// Use adapter for all event processing
|
||||
adapter.processEvent(event);
|
||||
@ -878,10 +951,24 @@ export async function runNonInteractive(
|
||||
|
||||
for await (const event of itemStream) {
|
||||
if (abortController.signal.aborted) {
|
||||
// Pair the startAssistantMessage() above so stream-json mode doesn't
|
||||
// leave an unterminated message_start.
|
||||
// Pair the startAssistantMessage() above so stream-json
|
||||
// mode doesn't leave an unterminated message_start, then
|
||||
// route through `routeAbort` so a budget overrun in the
|
||||
// final drain item surfaces as exit code 55 instead of
|
||||
// being silently swallowed by the outer success path
|
||||
// (drain-loop fall-through; see issue #4103 review).
|
||||
//
|
||||
// Also flush queued task notifications and finalize
|
||||
// one-shot monitors here. Previously this site used a
|
||||
// bare `return` and let control fall through to the
|
||||
// outer holdback loop, which did the flushing before
|
||||
// exiting; routing through `routeAbort` skips that
|
||||
// path, so we re-do it inline to preserve the
|
||||
// task_started↔task_notification pairing invariant.
|
||||
adapter.finalizeAssistantMessage();
|
||||
return;
|
||||
flushQueuedNotificationsToSdk(localQueue);
|
||||
finalizeOneShotMonitors();
|
||||
await routeAbort();
|
||||
}
|
||||
adapter.processEvent(event);
|
||||
if (event.type === GeminiEventType.ToolCallRequest) {
|
||||
@ -1033,12 +1120,12 @@ export async function runNonInteractive(
|
||||
while (true) {
|
||||
if (abortController.signal.aborted) {
|
||||
registry.abortAll();
|
||||
// Flush queued terminal notifications before handleCancellationError
|
||||
// exits so stream-json consumers always see a task_notification paired
|
||||
// with every task_started.
|
||||
// Flush queued terminal notifications before routeAbort
|
||||
// exits so stream-json consumers always see a task_notification
|
||||
// paired with every task_started.
|
||||
flushQueuedNotificationsToSdk(localQueue);
|
||||
finalizeOneShotMonitors();
|
||||
await handleCancellationError(config);
|
||||
await routeAbort();
|
||||
}
|
||||
// Once we enter the final holdback loop, monitor events should no
|
||||
// longer extend one-shot runtime. Already-queued events still drain
|
||||
@ -1145,8 +1232,22 @@ export async function runNonInteractive(
|
||||
flushQueuedNotificationsToSdk(localQueue);
|
||||
finalizeOneShotMonitors();
|
||||
|
||||
// If a run-level budget tripped during an awaited stream / tool
|
||||
// call, the underlying fetch's AbortError lands here before our
|
||||
// explicit `routeAbort` sites can fire. Capture the reason so we
|
||||
// can (a) include the friendly "Run aborted: …" message in the
|
||||
// adapter's terminal result envelope (STREAM_JSON consumers
|
||||
// depend on that envelope to close the stream cleanly) and (b)
|
||||
// exit with the budget handler's exit code 55 instead of the
|
||||
// generic `handleError` exit code 1 from a raw "AbortError".
|
||||
const budgetExceeded = budgetEnforcer.getExceeded();
|
||||
|
||||
// For JSON and STREAM_JSON modes, compute usage from metrics
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
const message = budgetExceeded
|
||||
? budgetExceeded.message
|
||||
: error instanceof Error
|
||||
? error.message
|
||||
: String(error);
|
||||
const metrics = uiTelemetryService.getMetrics();
|
||||
const usage = computeUsageFromMetrics(metrics);
|
||||
// Get stats for JSON format output
|
||||
@ -1167,18 +1268,43 @@ export async function runNonInteractive(
|
||||
outputFormat === OutputFormat.TEXT && isAlreadyReportedError;
|
||||
|
||||
if (!skipAdapterEmit) {
|
||||
adapter.emitResult({
|
||||
isError: true,
|
||||
durationMs: Date.now() - startTime,
|
||||
apiDurationMs: totalApiDurationMs,
|
||||
numTurns: turnCount,
|
||||
errorMessage: message,
|
||||
usage,
|
||||
stats,
|
||||
});
|
||||
// Wrap in try/catch: emitResult eventually hits stdout.write, which
|
||||
// can throw on EPIPE / ERR_STREAM_WRITE_AFTER_END when a piped
|
||||
// consumer closes early (`qwen -p ... | head -n 1` is the common
|
||||
// case). Letting that throw bubble out skips `handleBudgetExceededError`
|
||||
// / `handleError` below, dropping the documented exit code 55
|
||||
// contract — precisely when stdout is in trouble. Best-effort emit
|
||||
// and continue to the exit handler.
|
||||
try {
|
||||
adapter.emitResult({
|
||||
isError: true,
|
||||
durationMs: Date.now() - startTime,
|
||||
apiDurationMs: totalApiDurationMs,
|
||||
numTurns: turnCount,
|
||||
errorMessage: message,
|
||||
usage,
|
||||
stats,
|
||||
});
|
||||
} catch (emitErr) {
|
||||
debugLogger.error(
|
||||
`Failed to emit terminal result envelope: ${
|
||||
emitErr instanceof Error ? emitErr.message : String(emitErr)
|
||||
}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
if (budgetExceeded) {
|
||||
// Always exit AFTER emitResult so STREAM_JSON / JSON consumers
|
||||
// see a terminal result envelope before the process dies.
|
||||
await handleBudgetExceededError(config, budgetExceeded);
|
||||
}
|
||||
await handleError(error, config);
|
||||
} finally {
|
||||
// Cancel the wall-clock timer so it doesn't fire after a successful
|
||||
// run completes — important for callers (e.g. the `qwen serve`
|
||||
// daemon, SDK) that reuse a single process across many runs.
|
||||
budgetEnforcer.stop();
|
||||
|
||||
const reg = config.getBackgroundTaskRegistry();
|
||||
reg.setNotificationCallback(undefined);
|
||||
reg.setRegisterCallback(undefined);
|
||||
|
||||
@ -1,414 +0,0 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2025 Qwen Team
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import { writeStderrLine } from '../../utils/stdioHelpers.js';
|
||||
import { logSafe } from './jsonRpc.js';
|
||||
import type { SseStream } from './sseStream.js';
|
||||
|
||||
/**
|
||||
* Per-stream cap on frames buffered before the client attaches its SSE
|
||||
* stream. Mirrors the EventBus's `maxQueued` backpressure cap so a client
|
||||
* that drives requests without ever opening a stream can't grow daemon
|
||||
* memory without bound. Oldest frames are dropped past the cap.
|
||||
*/
|
||||
const MAX_BUFFERED_FRAMES = 256;
|
||||
|
||||
/** Default cap on concurrent live connections (mirrors a bounded resource). */
|
||||
const DEFAULT_MAX_CONNECTIONS = 64;
|
||||
|
||||
/**
|
||||
* Invoked when a session/connection tears down while an agent→client
|
||||
* request (e.g. a permission prompt) is still outstanding, so the bridge
|
||||
* isn't left blocked awaiting a vote that will never arrive.
|
||||
*/
|
||||
export type AbandonPendingFn = (
|
||||
req: PendingClientRequest,
|
||||
clientId: string | undefined,
|
||||
) => boolean;
|
||||
|
||||
/**
|
||||
* Best-effort bridge detach for a session's bridge-stamped clientId on
|
||||
* teardown. Without it, `session/new`/`load`/`resume`-registered client ids
|
||||
* stay visible in `knownClientIds()`/`votersForSession()` after the ACP
|
||||
* connection is gone — skewing permission mediation + origin validation.
|
||||
* ACP clients can't clean this up themselves (the id isn't on the wire).
|
||||
*/
|
||||
export type DetachSessionFn = (
|
||||
sessionId: string,
|
||||
clientId: string | undefined,
|
||||
) => void;
|
||||
|
||||
/**
|
||||
* Tracks one logical ACP-over-HTTP connection (RFD #721). A connection is
|
||||
* minted at `initialize`, keyed by `Acp-Connection-Id`, and may host many
|
||||
* sessions — each with its own session-scoped SSE stream.
|
||||
*/
|
||||
export interface SessionBinding {
|
||||
sessionId: string;
|
||||
/**
|
||||
* The clientId the bridge STAMPED for this session at create/attach.
|
||||
* The bridge ignores caller-supplied ids it has never issued and mints
|
||||
* a fresh one (returned on `spawnOrAttach`/`loadSession`), so every
|
||||
* later per-session call (`sendPrompt`, permission votes, …) must echo
|
||||
* THIS id, not the connection's own — otherwise the bridge rejects it
|
||||
* with "client id is not registered for session".
|
||||
*/
|
||||
clientId?: string;
|
||||
/** Session-scoped SSE stream (the client's `GET /acp` with both headers). */
|
||||
stream?: SseStream;
|
||||
/** Frames emitted before the session stream attached, flushed on attach. */
|
||||
buffer: unknown[];
|
||||
/**
|
||||
* Aborts the bridge event subscription tied to the CURRENT session
|
||||
* stream. Replaced with a fresh controller on every re-attach — a
|
||||
* controller, once aborted (on stream close), can never resume, so
|
||||
* reusing it across reconnects would leave the new stream permanently
|
||||
* event-starved.
|
||||
*/
|
||||
abort: AbortController;
|
||||
/**
|
||||
* Aborts the in-flight `session/prompt` for this session. Set by
|
||||
* `handlePrompt` while a prompt runs; aborted on `session/cancel` and on
|
||||
* session/connection teardown so a disconnecting client doesn't leave
|
||||
* the agent burning model quota on a result nobody will read.
|
||||
*/
|
||||
promptAbort?: AbortController;
|
||||
}
|
||||
|
||||
/** An agent→client request awaiting the client's JSON-RPC response. */
|
||||
export interface PendingClientRequest {
|
||||
sessionId: string;
|
||||
/** Maps the JSON-RPC id we issued back to the bridge's permission id. */
|
||||
bridgeRequestId: string;
|
||||
kind: 'permission';
|
||||
}
|
||||
|
||||
export class AcpConnection {
|
||||
readonly connectionId: string;
|
||||
/** Connection-scoped SSE stream (the client's `GET /acp` with only the conn header). */
|
||||
connStream?: SseStream;
|
||||
/** Frames emitted before the connection stream attached, flushed on attach. */
|
||||
private readonly connBuffer: unknown[] = [];
|
||||
readonly sessions = new Map<string, SessionBinding>();
|
||||
/**
|
||||
* Sessions this connection created (`session/new`) or explicitly
|
||||
* attached to (`session/load`/`resume`). Per-session operations
|
||||
* (subscribe, prompt, cancel, …) are gated on membership here so one
|
||||
* connection can't drive or eavesdrop on a session it never claimed.
|
||||
*/
|
||||
readonly ownedSessions = new Set<string>();
|
||||
/**
|
||||
* Sessions with an in-flight `session/close` (between the synchronous
|
||||
* ownership-revoke and the bridge close + local teardown). `session/load`
|
||||
* / `resume` reject for an id in this set so a close racing a re-load
|
||||
* can't have its `finally` teardown destroy the freshly-loaded session.
|
||||
*/
|
||||
readonly closingSessions = new Set<string>();
|
||||
/** Agent→client requests awaiting a client response, keyed by JSON-RPC id. */
|
||||
readonly pending = new Map<string, PendingClientRequest>();
|
||||
/** Daemon-issued client id reused across this connection's bridge calls. */
|
||||
readonly clientId: string;
|
||||
/**
|
||||
* True when the `initialize` POST arrived from a kernel-stamped loopback
|
||||
* peer. Threaded into per-session bridge contexts so the `local-only`
|
||||
* permission policy can gate votes by transport — mirrors the REST
|
||||
* surface's `detectFromLoopback(req)`. NOT derived from forgeable
|
||||
* headers (`X-Forwarded-For` etc).
|
||||
*/
|
||||
readonly fromLoopback: boolean;
|
||||
/**
|
||||
* Set by `destroy()`. An in-flight `session/new`/`load`/`resume` whose
|
||||
* bridge call resolves AFTER teardown checks this to kill/detach the
|
||||
* late-registered session, so a `DELETE` (or idle sweep) racing a spawn
|
||||
* doesn't orphan a child process / phantom clientId.
|
||||
*/
|
||||
destroyed = false;
|
||||
/**
|
||||
* Grace-period reap timer armed when the connection-scoped SSE stream
|
||||
* closes; cleared on reconnect (`attachConnStream`) or teardown. Avoids a
|
||||
* dead connection locking its `ownedSessions` (and counting against
|
||||
* `maxConnections`) for the full 30-min idle TTL.
|
||||
*/
|
||||
connGraceTimer?: ReturnType<typeof setTimeout>;
|
||||
lastActiveMs: number = Date.now();
|
||||
private idCounter = 0;
|
||||
|
||||
constructor(
|
||||
connectionId: string | undefined,
|
||||
fromLoopback: boolean,
|
||||
private readonly onAbandonPending?: AbandonPendingFn,
|
||||
private readonly onDetachSession?: DetachSessionFn,
|
||||
) {
|
||||
this.connectionId = connectionId ?? randomUUID();
|
||||
this.clientId = randomUUID();
|
||||
this.fromLoopback = fromLoopback;
|
||||
}
|
||||
|
||||
/**
|
||||
* Allocate a fresh JSON-RPC id for an agent→client request. STRING-typed
|
||||
* (`_qwen_perm_N`) so it can never collide with a client-originated id —
|
||||
* JSON-RPC 2.0 permits clients to use any number (incl. negatives) or
|
||||
* string, so a numeric namespace wasn't actually safe.
|
||||
*/
|
||||
nextId(): string {
|
||||
this.idCounter += 1;
|
||||
return `_qwen_perm_${this.idCounter}`;
|
||||
}
|
||||
|
||||
touch(): void {
|
||||
this.lastActiveMs = Date.now();
|
||||
}
|
||||
|
||||
ownSession(sessionId: string): void {
|
||||
this.ownedSessions.add(sessionId);
|
||||
}
|
||||
|
||||
ownsSession(sessionId: string): boolean {
|
||||
return this.ownedSessions.has(sessionId);
|
||||
}
|
||||
|
||||
getOrCreateSession(sessionId: string): SessionBinding {
|
||||
let binding = this.sessions.get(sessionId);
|
||||
if (!binding) {
|
||||
binding = { sessionId, abort: new AbortController(), buffer: [] };
|
||||
this.sessions.set(sessionId, binding);
|
||||
}
|
||||
return binding;
|
||||
}
|
||||
|
||||
/** Send a frame on the connection-scoped stream (buffer until it attaches). */
|
||||
sendConn(frame: unknown): void {
|
||||
if (this.connStream && !this.connStream.isClosed) {
|
||||
void this.connStream.send(frame);
|
||||
} else {
|
||||
pushCapped(this.connBuffer, frame, `conn ${this.connectionId}`);
|
||||
}
|
||||
}
|
||||
|
||||
/** True if any session currently has a live (open) SSE stream. */
|
||||
hasLiveSessionStream(): boolean {
|
||||
for (const b of this.sessions.values()) {
|
||||
if (b.stream && !b.stream.isClosed) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/** Cancel a pending grace-period reap (e.g. on conn-stream reconnect). */
|
||||
clearGraceTimer(): void {
|
||||
if (this.connGraceTimer) {
|
||||
clearTimeout(this.connGraceTimer);
|
||||
this.connGraceTimer = undefined;
|
||||
}
|
||||
}
|
||||
|
||||
/** Attach the connection-scoped stream and flush any buffered frames. */
|
||||
attachConnStream(stream: SseStream): void {
|
||||
// A reconnect cancels any pending grace-period reap.
|
||||
this.clearGraceTimer();
|
||||
// Close any prior connection stream so its heartbeat interval + socket
|
||||
// don't leak when a client reconnects the connection-scoped GET.
|
||||
if (this.connStream && this.connStream !== stream) this.connStream.close();
|
||||
this.connStream = stream;
|
||||
for (const frame of this.connBuffer.splice(0)) void stream.send(frame);
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a frame on a session-scoped stream (buffer until it attaches).
|
||||
* LOOKUP-ONLY: drops the frame when the session has no binding — a binding
|
||||
* always exists for a live session (created at `session/new`/`load`/
|
||||
* `resume`), so a missing one means the session was torn down. Auto-
|
||||
* creating here would resurrect a ghost binding (no stream, no owner) that
|
||||
* buffers up to 256 late pump/reply frames forever.
|
||||
*/
|
||||
sendSession(sessionId: string, frame: unknown): void {
|
||||
const binding = this.sessions.get(sessionId);
|
||||
if (!binding) return;
|
||||
if (binding.stream && !binding.stream.isClosed) {
|
||||
void binding.stream.send(frame);
|
||||
} else {
|
||||
pushCapped(binding.buffer, frame, `session ${sessionId}`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Attach a session-scoped stream: close any prior stream, abort the prior
|
||||
* subscription, install the caller's FRESH AbortController (the old one is
|
||||
* aborted and can never resume — reusing it would leave the new stream
|
||||
* event-starved), flush buffered frames, and return the binding.
|
||||
*/
|
||||
attachSessionStream(
|
||||
sessionId: string,
|
||||
stream: SseStream,
|
||||
abort: AbortController,
|
||||
): SessionBinding {
|
||||
const binding = this.getOrCreateSession(sessionId);
|
||||
const prevStream = binding.stream;
|
||||
binding.abort.abort();
|
||||
binding.abort = abort;
|
||||
// Install the NEW stream BEFORE closing the old one. The old stream's
|
||||
// `onClose` is identity-guarded on `binding.stream` (see the session-GET
|
||||
// handler in `index.ts` — `if (conn.sessions.get(sessionId)?.stream ===
|
||||
// stream) ...promptAbort?.abort()`), so installing first means a
|
||||
// reconnect's close can't abort the in-flight prompt (the client is
|
||||
// reconnecting, not leaving — the prompt must survive). CONTRACT: that
|
||||
// identity guard and this ordering must stay in lockstep.
|
||||
binding.stream = stream;
|
||||
if (prevStream && prevStream !== stream) prevStream.close();
|
||||
for (const frame of binding.buffer.splice(0)) void stream.send(frame);
|
||||
return binding;
|
||||
}
|
||||
|
||||
closeSessionStream(sessionId: string): void {
|
||||
const binding = this.sessions.get(sessionId);
|
||||
if (!binding) return;
|
||||
binding.abort.abort();
|
||||
binding.promptAbort?.abort();
|
||||
binding.stream?.close();
|
||||
this.abandonPendingForSession(sessionId, binding.clientId);
|
||||
this.onDetachSession?.(sessionId, binding.clientId);
|
||||
this.sessions.delete(sessionId);
|
||||
this.ownedSessions.delete(sessionId);
|
||||
}
|
||||
|
||||
destroy(): void {
|
||||
this.destroyed = true;
|
||||
this.clearGraceTimer();
|
||||
for (const binding of this.sessions.values()) {
|
||||
binding.abort.abort();
|
||||
binding.promptAbort?.abort();
|
||||
binding.stream?.close();
|
||||
this.abandonPendingForSession(binding.sessionId, binding.clientId);
|
||||
// Release the bridge-stamped clientId so it doesn't linger in the
|
||||
// bridge's voter/known-client sets after this connection is gone.
|
||||
this.onDetachSession?.(binding.sessionId, binding.clientId);
|
||||
}
|
||||
this.sessions.clear();
|
||||
this.ownedSessions.clear();
|
||||
this.pending.clear();
|
||||
this.connStream?.close();
|
||||
}
|
||||
|
||||
/**
|
||||
* Cancel + drop any pending agent→client requests for a closing session.
|
||||
* This is the LAST-RESORT recovery path: `resolveClientResponse` retains a
|
||||
* pending entry on double-failure (vote AND cancel both threw) precisely so
|
||||
* this teardown sweep can retry the cancel. We always drop the entry here
|
||||
* (the connection is going away — there is no further retry after teardown),
|
||||
* but if the cancel itself still fails (triple-failure) the bridge mediator
|
||||
* may be stuck awaiting a vote that will never arrive, so log it for the
|
||||
* operator rather than failing silently.
|
||||
*/
|
||||
private abandonPendingForSession(
|
||||
sessionId: string,
|
||||
clientId: string | undefined,
|
||||
): void {
|
||||
for (const [id, req] of this.pending) {
|
||||
if (req.sessionId !== sessionId) continue;
|
||||
this.pending.delete(id);
|
||||
const cancelled = this.onAbandonPending?.(req, clientId) ?? true;
|
||||
if (!cancelled) {
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp MEDIATOR STUCK: abandonPendingForSession(${logSafe(sessionId)}) cancel failed for ${logSafe(req.bridgeRequestId)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function pushCapped(buf: unknown[], frame: unknown, label = 'stream'): void {
|
||||
if (buf.length >= MAX_BUFFERED_FRAMES) {
|
||||
buf.shift();
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp pre-attach buffer full (${label}), dropped oldest frame`,
|
||||
);
|
||||
}
|
||||
buf.push(frame);
|
||||
}
|
||||
|
||||
/**
|
||||
* Registry of live ACP connections with an idle-TTL sweep. The sweep is
|
||||
* defensive: a well-behaved client `DELETE /acp`s, but a crashed client
|
||||
* that never closes its streams would otherwise leak connection state.
|
||||
*/
|
||||
export class ConnectionRegistry {
|
||||
private readonly byId = new Map<string, AcpConnection>();
|
||||
private readonly sweepTimer: ReturnType<typeof setInterval>;
|
||||
|
||||
constructor(
|
||||
private readonly onAbandonPending?: AbandonPendingFn,
|
||||
private readonly onDetachSession?: DetachSessionFn,
|
||||
private readonly maxConnections = DEFAULT_MAX_CONNECTIONS,
|
||||
private readonly idleTtlMs = 30 * 60_000,
|
||||
) {
|
||||
this.sweepTimer = setInterval(() => this.sweep(), 60_000);
|
||||
this.sweepTimer.unref();
|
||||
}
|
||||
|
||||
/**
|
||||
* Mint a connection, or return `undefined` when the live-connection cap
|
||||
* is reached (the caller answers `503`). Bounds an `initialize` flood from
|
||||
* growing the registry without limit through the full TTL window.
|
||||
*/
|
||||
create(fromLoopback: boolean): AcpConnection | undefined {
|
||||
if (this.maxConnections > 0 && this.byId.size >= this.maxConnections) {
|
||||
return undefined;
|
||||
}
|
||||
const conn = new AcpConnection(
|
||||
undefined,
|
||||
fromLoopback,
|
||||
this.onAbandonPending,
|
||||
this.onDetachSession,
|
||||
);
|
||||
this.byId.set(conn.connectionId, conn);
|
||||
return conn;
|
||||
}
|
||||
|
||||
get(connectionId: string | undefined): AcpConnection | undefined {
|
||||
if (!connectionId) return undefined;
|
||||
const conn = this.byId.get(connectionId);
|
||||
conn?.touch();
|
||||
return conn;
|
||||
}
|
||||
|
||||
delete(connectionId: string): boolean {
|
||||
const conn = this.byId.get(connectionId);
|
||||
if (!conn) return false;
|
||||
conn.destroy();
|
||||
return this.byId.delete(connectionId);
|
||||
}
|
||||
|
||||
get size(): number {
|
||||
return this.byId.size;
|
||||
}
|
||||
|
||||
/** The configured concurrent-connection cap (for operator-facing logs). */
|
||||
get connectionCap(): number {
|
||||
return this.maxConnections;
|
||||
}
|
||||
|
||||
dispose(): void {
|
||||
clearInterval(this.sweepTimer);
|
||||
for (const id of [...this.byId.keys()]) this.delete(id);
|
||||
}
|
||||
|
||||
private sweep(): void {
|
||||
const cutoff = Date.now() - this.idleTtlMs;
|
||||
for (const [id, conn] of this.byId) {
|
||||
if (conn.lastActiveMs >= cutoff) continue;
|
||||
// Observability: a reaped connection silently dropping its SSE
|
||||
// streams is otherwise invisible to operators chasing "my client
|
||||
// froze". Note that `touch()` fires on inbound HTTP AND on event
|
||||
// delivery (pumpSessionEvents), so a long quiet prompt isn't reaped.
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp reaping idle connection ${id} ` +
|
||||
`(idle > ${Math.round(this.idleTtlMs / 60_000)}m, ` +
|
||||
`${conn.sessions.size} session(s))`,
|
||||
);
|
||||
this.delete(id);
|
||||
}
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,322 +0,0 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2025 Qwen Team
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import type { Application, Request, Response } from 'express';
|
||||
import type { HttpAcpBridge } from '@qwen-code/acp-bridge/bridgeTypes';
|
||||
import { writeStderrLine } from '../../utils/stdioHelpers.js';
|
||||
import { AcpDispatcher } from './dispatch.js';
|
||||
import { ConnectionRegistry } from './connectionRegistry.js';
|
||||
import { SseStream } from './sseStream.js';
|
||||
import { RPC, error as rpcError, isRequest, parseInbound } from './jsonRpc.js';
|
||||
|
||||
export const ACP_CONNECTION_HEADER = 'acp-connection-id';
|
||||
export const ACP_SESSION_HEADER = 'acp-session-id';
|
||||
|
||||
/**
|
||||
* Grace window after the connection-scoped SSE stream closes before the
|
||||
* connection is reaped (if not reconnected and no session stream is live).
|
||||
* Long enough to ride out a transient blip / reconnect, short enough to free
|
||||
* `ownedSessions` + a `maxConnections` slot well before the 30-min idle TTL.
|
||||
*/
|
||||
const CONN_GRACE_MS = 10_000;
|
||||
|
||||
export interface MountAcpHttpOptions {
|
||||
boundWorkspace: string;
|
||||
/** Defaults to `process.env.QWEN_SERVE_ACP_HTTP !== '0'`. */
|
||||
enabled?: boolean;
|
||||
/** Mount path; defaults to `/acp`. */
|
||||
path?: string;
|
||||
/** Concurrent-connection cap; `0` disables. Defaults to the registry default. */
|
||||
maxConnections?: number;
|
||||
}
|
||||
|
||||
export interface AcpHttpHandle {
|
||||
dispose(): void;
|
||||
registry: ConnectionRegistry;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mount the official ACP Streamable HTTP transport (RFD #721) on an
|
||||
* existing Express app, backed by the shared `HttpAcpBridge`. Additive:
|
||||
* the REST surface (`/session/*`) is untouched (design doc §6).
|
||||
*
|
||||
* Wire shape (single `/acp` endpoint):
|
||||
* - POST {initialize} → 200 + capabilities JSON + `Acp-Connection-Id`
|
||||
* - POST {other} → 202; reply delivered on a long-lived SSE stream
|
||||
* - GET (conn header) → connection-scoped SSE stream
|
||||
* - GET (conn+session)→ session-scoped SSE stream
|
||||
* - DELETE → 202; tears the connection down
|
||||
*/
|
||||
export function mountAcpHttp(
|
||||
app: Application,
|
||||
bridge: HttpAcpBridge,
|
||||
opts: MountAcpHttpOptions,
|
||||
): AcpHttpHandle | undefined {
|
||||
const enabled = opts.enabled ?? process.env['QWEN_SERVE_ACP_HTTP'] !== '0';
|
||||
if (!enabled) return undefined;
|
||||
|
||||
const path = opts.path ?? '/acp';
|
||||
const dispatcher = new AcpDispatcher(bridge, opts.boundWorkspace);
|
||||
// When a session/connection tears down with a permission still pending,
|
||||
// cancel it on the bridge so the agent's prompt isn't left blocked.
|
||||
const registry = new ConnectionRegistry(
|
||||
(req, clientId) => dispatcher.cancelAbandonedPermission(req, clientId),
|
||||
// Best-effort bridge detach so a torn-down connection's bridge-stamped
|
||||
// client ids don't linger in the bridge's voter/known-client sets.
|
||||
(sessionId, clientId) => {
|
||||
void bridge.detachClient(sessionId, clientId).catch((err: unknown) => {
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp detachClient(${sessionId}) failed: ${
|
||||
err instanceof Error ? err.message : String(err)
|
||||
}`,
|
||||
);
|
||||
});
|
||||
},
|
||||
opts.maxConnections,
|
||||
);
|
||||
|
||||
// ── POST /acp ──────────────────────────────────────────────────────
|
||||
app.post(path, async (req: Request, res: Response) => {
|
||||
const parsed = parseInbound(req.body);
|
||||
if (!parsed.ok) {
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp malformed request from ${req.socket?.remoteAddress}: ${parsed.error.error.message}`,
|
||||
);
|
||||
res.status(400).json(parsed.error);
|
||||
return;
|
||||
}
|
||||
const message = parsed.message;
|
||||
|
||||
// `initialize` mints a connection and replies inline (200 + JSON).
|
||||
if (isRequest(message) && message.method === 'initialize') {
|
||||
const conn = registry.create(isLoopbackReq(req));
|
||||
if (!conn) {
|
||||
// Connection cap reached — shed load rather than grow unbounded.
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp connection cap reached (max=${registry.connectionCap}), rejecting initialize`,
|
||||
);
|
||||
res.setHeader('Retry-After', '5');
|
||||
res
|
||||
.status(503)
|
||||
.json(
|
||||
rpcError(
|
||||
message.id,
|
||||
RPC.INTERNAL_ERROR,
|
||||
'Too many ACP connections; retry later',
|
||||
),
|
||||
);
|
||||
return;
|
||||
}
|
||||
const requestedVersion =
|
||||
message.params &&
|
||||
typeof message.params === 'object' &&
|
||||
!Array.isArray(message.params)
|
||||
? (message.params as Record<string, unknown>)['protocolVersion']
|
||||
: undefined;
|
||||
res.setHeader('Acp-Connection-Id', conn.connectionId);
|
||||
res.status(200).json({
|
||||
// success envelope: clients correlate by the request id.
|
||||
jsonrpc: '2.0',
|
||||
id: message.id,
|
||||
result: dispatcher.buildInitializeResult(
|
||||
conn.connectionId,
|
||||
requestedVersion,
|
||||
),
|
||||
});
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp connection established ${conn.connectionId.slice(0, 8)} ` +
|
||||
`(loopback=${conn.fromLoopback}, active=${registry.size})`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
const conn = registry.get(headerOf(req, ACP_CONNECTION_HEADER));
|
||||
if (!conn) {
|
||||
res
|
||||
.status(400)
|
||||
.json(
|
||||
rpcError(
|
||||
isRequest(message) ? message.id : null,
|
||||
RPC.INVALID_REQUEST,
|
||||
'Missing or unknown Acp-Connection-Id',
|
||||
),
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
// Per RFD: non-initialize POST acks 202; the reply rides an SSE stream.
|
||||
res.status(202).end();
|
||||
// Response already sent — `handle` delivers everything else over SSE, so
|
||||
// swallow+log any late rejection rather than let it escape as an
|
||||
// unhandled rejection (which could take the daemon down).
|
||||
await dispatcher
|
||||
.handle(
|
||||
conn,
|
||||
message,
|
||||
headerOf(req, ACP_SESSION_HEADER),
|
||||
isLoopbackReq(req),
|
||||
)
|
||||
.catch((err: unknown) => {
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp handle error: ${
|
||||
err instanceof Error ? err.message : String(err)
|
||||
}`,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
// ── GET /acp (SSE) ─────────────────────────────────────────────────
|
||||
app.get(path, (req: Request, res: Response) => {
|
||||
const conn = registry.get(headerOf(req, ACP_CONNECTION_HEADER));
|
||||
if (!conn) {
|
||||
res.status(400).json({ error: 'Missing or unknown Acp-Connection-Id' });
|
||||
return;
|
||||
}
|
||||
const sessionId = headerOf(req, ACP_SESSION_HEADER);
|
||||
|
||||
if (!sessionId) {
|
||||
// Connection-scoped stream. onClose logs the disconnect so a
|
||||
// half-dead connection (conn stream gone, replies silently buffering)
|
||||
// leaves an operator breadcrumb.
|
||||
const connId = conn.connectionId;
|
||||
const stream = new SseStream(
|
||||
res,
|
||||
() => {
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp connection stream closed (${connId.slice(0, 8)})`,
|
||||
);
|
||||
// Grace-period reap: a dead connection otherwise locks its
|
||||
// ownedSessions + counts against maxConnections for the full 30-min
|
||||
// idle TTL. After the grace window, reap UNLESS a reconnect
|
||||
// re-attached the conn stream (clears the timer) OR a session
|
||||
// stream is still live (client is active — only the conn stream
|
||||
// blipped, don't kill its sessions/prompts).
|
||||
conn.clearGraceTimer();
|
||||
conn.connGraceTimer = setTimeout(() => {
|
||||
if (
|
||||
registry.get(connId) === conn &&
|
||||
conn.connStream === stream &&
|
||||
!conn.hasLiveSessionStream()
|
||||
) {
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp reaping connection ${connId.slice(0, 8)} (conn stream gone, no live session stream)`,
|
||||
);
|
||||
registry.delete(connId);
|
||||
}
|
||||
}, CONN_GRACE_MS);
|
||||
conn.connGraceTimer.unref?.();
|
||||
},
|
||||
() => conn.touch(),
|
||||
);
|
||||
stream.open();
|
||||
conn.attachConnStream(stream);
|
||||
return;
|
||||
}
|
||||
|
||||
// Session-scoped stream — only for a session THIS connection owns
|
||||
// (created via session/new or attached via session/load|resume). Stops
|
||||
// one connection eavesdropping on another's session event stream.
|
||||
if (!conn.ownsSession(sessionId)) {
|
||||
res.status(403).json({ error: 'Session not owned by this connection' });
|
||||
return;
|
||||
}
|
||||
|
||||
// Fresh controller per stream so a reconnect gets a live (non-aborted)
|
||||
// signal; `attachSessionStream` installs it and tears down any prior
|
||||
// stream/subscription. onClose aborts THIS stream's controller — a
|
||||
// stale stream closing can't cancel a newer subscription.
|
||||
const ac = new AbortController();
|
||||
const stream = new SseStream(
|
||||
res,
|
||||
() => {
|
||||
// Stream closed (tab close / network drop / crash): stop the event
|
||||
// pump AND abort any in-flight prompt for this session — otherwise
|
||||
// the agent keeps running (quota, FIFO) until idle TTL.
|
||||
ac.abort();
|
||||
// BUT only abort the prompt when THIS is still the session's live
|
||||
// stream. A reconnect already installed a newer stream — the prompt
|
||||
// must survive the old stream's close. CONTRACT: this identity guard
|
||||
// pairs with `attachSessionStream`'s install-before-close ordering
|
||||
// (connectionRegistry.ts) — keep both in lockstep.
|
||||
if (conn.sessions.get(sessionId)?.stream === stream) {
|
||||
conn.sessions.get(sessionId)?.promptAbort?.abort();
|
||||
}
|
||||
},
|
||||
() => conn.touch(),
|
||||
);
|
||||
// Open (write SSE headers + `retry:`) BEFORE attaching, so the protocol
|
||||
// handshake precedes any buffered frames the attach flushes.
|
||||
stream.open();
|
||||
conn.attachSessionStream(sessionId, stream, ac);
|
||||
// Identity-guarded close: only tear down if THIS stream is still the
|
||||
// session's current one (a reconnect between settle and this microtask
|
||||
// would otherwise kill the fresh stream).
|
||||
const closeIfCurrent = () => {
|
||||
if (conn.sessions.get(sessionId)?.stream === stream) {
|
||||
conn.closeSessionStream(sessionId);
|
||||
}
|
||||
};
|
||||
void dispatcher.pumpSessionEvents(conn, sessionId, ac.signal).then(
|
||||
// NORMAL completion (iterator returned `done` — subprocess ended): close
|
||||
// so the stream isn't a zombie heartbeating with nothing left to deliver.
|
||||
closeIfCurrent,
|
||||
(err: unknown) => {
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp event pump error (${sessionId}): ${
|
||||
err instanceof Error ? err.message : String(err)
|
||||
}`,
|
||||
);
|
||||
closeIfCurrent();
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
// ── DELETE /acp ────────────────────────────────────────────────────
|
||||
app.delete(path, (req: Request, res: Response) => {
|
||||
const connectionId = headerOf(req, ACP_CONNECTION_HEADER);
|
||||
if (!connectionId) {
|
||||
res.status(400).json({ error: 'Missing Acp-Connection-Id' });
|
||||
return;
|
||||
}
|
||||
// NOTE: like every other route, DELETE is gated only by the bearer
|
||||
// token — the daemon's trust boundary is "holds the token for this
|
||||
// single-workspace daemon", so any token-holder may tear down any
|
||||
// connection (same posture as the REST `DELETE /session/:id`). A
|
||||
// per-connection secret would add intra-token isolation; deferred with
|
||||
// the rest of the multi-tenant hardening (design §7).
|
||||
const existed = registry.delete(connectionId);
|
||||
if (existed) {
|
||||
writeStderrLine(
|
||||
`qwen serve: /acp connection deleted ${connectionId.slice(0, 8)} (remaining=${registry.size})`,
|
||||
);
|
||||
}
|
||||
res.status(202).end();
|
||||
});
|
||||
|
||||
return { dispose: () => registry.dispose(), registry };
|
||||
}
|
||||
|
||||
function headerOf(req: Request, name: string): string | undefined {
|
||||
const v = req.headers[name];
|
||||
return Array.isArray(v) ? v[0] : v;
|
||||
}
|
||||
|
||||
/**
|
||||
* True when the request's KERNEL-stamped peer address is loopback. Mirrors
|
||||
* the REST surface's `detectFromLoopback` (NOT derived from forgeable
|
||||
* headers like `X-Forwarded-For`). Replicated here rather than imported
|
||||
* from `server.ts` to avoid a server↔acpHttp import cycle.
|
||||
*/
|
||||
function isLoopbackReq(req: Request): boolean {
|
||||
const addr = req.socket?.remoteAddress;
|
||||
if (typeof addr !== 'string') return false;
|
||||
// Match the REST surface's `detectFromLoopback`: the full 127.0.0.0/8
|
||||
// range + the IPv4-mapped block, not just three exact literals (a
|
||||
// container peer on 127.0.0.2 is legal loopback).
|
||||
return (
|
||||
addr === '::1' || addr.startsWith('127.') || addr.startsWith('::ffff:127.')
|
||||
);
|
||||
}
|
||||
@ -1,74 +0,0 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2025 Qwen Team
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
isNotification,
|
||||
isRequest,
|
||||
isResponse,
|
||||
parseInbound,
|
||||
QWEN_METHOD_NS,
|
||||
RPC,
|
||||
} from './jsonRpc.js';
|
||||
|
||||
describe('jsonRpc helpers', () => {
|
||||
it('classifies a request', () => {
|
||||
const m = { jsonrpc: '2.0', id: 1, method: 'initialize' };
|
||||
expect(isRequest(m)).toBe(true);
|
||||
expect(isNotification(m)).toBe(false);
|
||||
expect(isResponse(m)).toBe(false);
|
||||
});
|
||||
|
||||
it('classifies a notification (no id)', () => {
|
||||
const m = { jsonrpc: '2.0', method: 'session/cancel' };
|
||||
expect(isNotification(m)).toBe(true);
|
||||
expect(isRequest(m)).toBe(false);
|
||||
});
|
||||
|
||||
it('classifies a response (result, no method)', () => {
|
||||
const m = { jsonrpc: '2.0', id: -1, result: { ok: true } };
|
||||
expect(isResponse(m)).toBe(true);
|
||||
expect(isRequest(m)).toBe(false);
|
||||
});
|
||||
|
||||
it('classifies an error response', () => {
|
||||
const m = { jsonrpc: '2.0', id: 2, error: { code: -1, message: 'x' } };
|
||||
expect(isResponse(m)).toBe(true);
|
||||
});
|
||||
|
||||
it('rejects a response with BOTH result and error (XOR); parseInbound → 400-shape', () => {
|
||||
const m = {
|
||||
jsonrpc: '2.0',
|
||||
id: 3,
|
||||
result: {},
|
||||
error: { code: -1, message: 'x' },
|
||||
};
|
||||
expect(isResponse(m)).toBe(false);
|
||||
const r = parseInbound(m);
|
||||
expect(r.ok).toBe(false);
|
||||
if (!r.ok) expect(r.error.error.code).toBe(RPC.INVALID_REQUEST);
|
||||
});
|
||||
|
||||
it('rejects JSON-RPC batch arrays', () => {
|
||||
const r = parseInbound([{ jsonrpc: '2.0', id: 1, method: 'x' }]);
|
||||
expect(r.ok).toBe(false);
|
||||
if (!r.ok) expect(r.error.error.code).toBe(RPC.INVALID_REQUEST);
|
||||
});
|
||||
|
||||
it('rejects malformed envelopes', () => {
|
||||
expect(parseInbound({ foo: 'bar' }).ok).toBe(false);
|
||||
expect(parseInbound(null).ok).toBe(false);
|
||||
});
|
||||
|
||||
it('accepts a well-formed request', () => {
|
||||
const r = parseInbound({ jsonrpc: '2.0', id: 1, method: 'session/new' });
|
||||
expect(r.ok).toBe(true);
|
||||
});
|
||||
|
||||
it('exposes the qwen extension namespace', () => {
|
||||
expect(QWEN_METHOD_NS).toBe('_qwen/');
|
||||
});
|
||||
});
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user