Repository navigation
feat(core): layered tool-output truncation, per-message budget, per-tool limits - #4880
Merged
Merged
Conversation
Contributor
Code Coverage Summary
CLI Package - Full Text ReportCore Package - Full Text ReportFor detailed HTML reports, please see the 'coverage-reports-22.x-ubuntu-latest' artifact from the main CI run. |
LaZzyMan
force-pushed
the
lazzy/wonderful-swirles-21920d
branch
from
June 9, 2026 04:00
da28e3e to
d55d31d
Compare
LaZzyMan
marked this pull request as ready for review
June 9, 2026 05:54
LaZzyMan
force-pushed
the
lazzy/wonderful-swirles-21920d
branch
from
June 9, 2026 08:58
d55d31d to
1a0f14f
Compare
LaZzyMan
force-pushed
the
lazzy/wonderful-swirles-21920d
branch
from
June 10, 2026 03:15
1a0f14f to
a33b678
Compare
Collaborator
Author
Round 7 — addressed in a33b678Fixed (2 Critical):
Declined as out of scope (5 Suggestions) — this PR bounds oversized tool output before it overflows the context window; none of these affect that behavior:
|
LaZzyMan
force-pushed
the
lazzy/wonderful-swirles-21920d
branch
from
June 10, 2026 03:57
a33b678 to
2279a6a
Compare
…ool limits Bound tool output before it enters conversation history, mirroring Claude Code's three-layer model: - Single-result: a per-tool/global char threshold spills oversized output to a temp file with a recoverable preview + read_file pointer; media parts are kept, with a token-aware fallback, 0600 owner-only perms on the spilled file, and a sentinel re-entrancy guard. - Per-message: when one batch of tool results exceeds toolOutputBatchBudget (default 200k chars), the largest results are offloaded to disk; a warning is logged if it still can't get under budget. - Per-tool: DeclarativeTool.maxOutputChars/truncateKeep getters (shell 30k, grep 20k, read-file self-managed, mcp 500k, agent 32k/tail). Truncation runs in CoreToolScheduler, deferring PostToolUse/skill metadata injection until after truncation so reminders are never bisected. Per-tool budgets are char-only so the global line cap can't undercut a self-managed tool (read-file) or a declared char budget (grep). The re-entrancy guard matches the truncation prefix at the start of the output so an injected copy of the phrase can't bypass the budget. Adds the toolOutputBatchBudget setting (core + CLI schema) and supporting tests.
LaZzyMan
force-pushed
the
lazzy/wonderful-swirles-21920d
branch
from
June 10, 2026 08:22
2279a6a to
cdfef51
Compare
Collaborator
Author
Round 8 — addressed in cdfef51Fixed (2):
Documented (1):
Declined (1):
|
DragonnZhang
approved these changes
Jun 10, 2026
DragonnZhang
left a comment
DragonnZhang
left a comment
Collaborator
There was a problem hiding this comment.
No issues found. LGTM! The layered truncation design is well-structured, the deferred metadata pattern correctly prevents system-reminder bisection, and the test coverage is thorough across keep-direction, token-aware fallback, per-tool budgets via legacy aliases, batch offload, and Part[] media preservation. CI is all green (30 checks). -- qwen3-coder-plus via Qwen Code /review
Collaborator
Independent runtime verification (Linux) — code looks merge-ready; PR evidence section needs correctionsVerified by building two real esbuild bundles — BEFORE ( Verdict: the implementation works as designed in everything I could exercise — but three claims in the PR's Evidence/Breaking-changes sections do not reproduce on either side of the A/B, and should be corrected (or their provenance explained) before merge so release notes don't inherit them. What entered history (captured provider requests, A/B)
Also confirmed AFTER: the in-tool shell truncation and the scheduler pass don't double-truncate (sentinel idempotency works — no nested headers), and
|
Collaborator
Author
|
@wenshao You're right on all three — the read_file evidence was stale (from an intermediate dev build before the
The two pre-existing issues (short-lived-process stdout race; shell ~60KB buffer cap making the spill non-full) reproduce identically on both A/B builds, so they are out of scope for this PR — not introduced here. |
wenshao
approved these changes
Jun 11, 2026
doudouOUC
pushed a commit
that referenced
this pull request
Jun 15, 2026
…ool limits (#4880) Bound tool output before it enters conversation history, mirroring Claude Code's three-layer model: - Single-result: a per-tool/global char threshold spills oversized output to a temp file with a recoverable preview + read_file pointer; media parts are kept, with a token-aware fallback, 0600 owner-only perms on the spilled file, and a sentinel re-entrancy guard. - Per-message: when one batch of tool results exceeds toolOutputBatchBudget (default 200k chars), the largest results are offloaded to disk; a warning is logged if it still can't get under budget. - Per-tool: DeclarativeTool.maxOutputChars/truncateKeep getters (shell 30k, grep 20k, read-file self-managed, mcp 500k, agent 32k/tail). Truncation runs in CoreToolScheduler, deferring PostToolUse/skill metadata injection until after truncation so reminders are never bisected. Per-tool budgets are char-only so the global line cap can't undercut a self-managed tool (read-file) or a declared char budget (grep). The re-entrancy guard matches the truncation prefix at the start of the output so an injected copy of the phrase can't bypass the budget. Adds the toolOutputBatchBudget setting (core + CLI schema) and supporting tests.
rbalachandar
pushed a commit
to rbalachandar/qwen-code
that referenced
this pull request
Aug 12, 2026
…M#8875) * feat(cli): report retained tool-result stats in /doctor memory Add a tool-result retention section to /doctor memory (and --json) covering the phase-1 diagnostics from QwenLM#4184: retained tool-result count/total/largest, oversized flagging against the 30k widest legal per-tool budget, plus duplication signals for UI history and compression input. Sizes and counts only (never content); history is scanned by reference so the diagnostic adds no memory pressure. * docs(design): document tool-output offload/preview state transitions and privacy model Satisfies acceptance criterion 2 of QwenLM#4184: state transitions of the layered truncation/offload mitigation (implemented in QwenLM#4880) and its privacy model, plus the tmux E2E report for the /doctor memory retention diagnostics. * fix(cli): align retention diagnostics with per-tool budgets and raw-char sizes Address review round 1: measure retained tool results with the compression pipeline's estimatePartChars (raw chars for string outputs, image estimate for nested media) instead of JSON.stringify, fixing false oversized flags on newline-dense compliant outputs; compare each result against its own tool's declared budget resolved from the tool registry instead of a fixed 30k threshold, so compliant high-budget results (e.g. MCP) are never flagged; scope the UI-history duplication scan to tool_group result displays so model text is excluded and rendered tool outputs are actually detected; omit toolResultRetention from --json when unavailable; log retention collection failures via debug logger; fix the design note's IO-error persistence bullet; re-verify the E2E report with the new measurement basis. * fix(cli): calibrate oversized detection against truncation layers - Canonicalize tool names before registry lookup (legacy aliases resolve) - Skip sentinel-prefixed results and apply combined-pass 2x tolerance - Fall back to configured global threshold for tools declaring no budget - Compare UI history displays against per-tool budgets - Document persistence gate in design note; re-verify e2e scenario 3 * fix(core): share tolerance constant and align imageTokenEstimate with compression pipeline Review (round 4) fixes: - R4-3: Extract COMBINED_PASS_TOLERANCE_FACTOR into truncation.ts and share it between the scheduler's combined pass and the retention diagnostics so both use the same tolerance factor. - R4-4: Add imageTokenEstimate option to analyzeToolResultRetention (defaults to DEFAULT_IMAGE_TOKEN_ESTIMATE); doctorCommand now resolves it via resolveSlimmingConfig (env > settings > default), the same source the compression pipeline uses. Export resolveSlimmingConfig from the core barrel. - R4-5/R4-6: Add tests for configurable imageTokenEstimate and Infinity threshold guard. - R4-7: Guard oversizedThresholdChars against Infinity — when truncation is disabled (threshold <= 0 → Infinity), report 0 instead of Infinity so JSON.stringify does not drop the key to null. - R3-3: Fix UI history budget resolution — IndividualToolCallDisplay.name stores the tool's displayName (e.g. 'Shell'), not the registry key (e.g. 'shell'), so getTool(displayName) returned undefined and budgets fell back to the global threshold. Build a displayName → maxOutputChars map from getAllTools() at scan time. - R4-12: Declare string-only scope for UI history scanning in code comment and design doc §5 — structured display objects (file diffs, ANSI captures, agent result summaries) are out of scope for phase 1. - 3750020138: Update design doc §5 to reflect resolveSlimmingConfig alignment and display-name map. * fix(doctor): align UI scan to 2x tolerance, fix threshold/error/sentinel gaps R5-1: threshold uses config.getTruncateToolOutputThreshold() first so disabled (Infinity) doesn't fall to 0 R5-3: UI scan uses budget * COMBINED_PASS_TOLERANCE_FACTOR to match API-history 2x tolerance R5-7: oversized check uses rawChars (output.length) instead of estimatePartChars (which adds 64 wrapper floor) R5-8: read output ?? error and check <persisted-output> sentinel R5-12: UI lookup consults ToolDisplayNamesMigration for legacy names Tests: 3 core + 1 CLI updated for rawChars/2x; 3 core + 2 CLI added Doc: test counts (core 14→19, CLI 9→11), scenario 4 JSON, 2x wording * docs: fix design note accuracy (R5-9/R5-15/R5-10) R5-9: clarify shell/MCP truncate in-tool before gate; split recovery paths R5-15: note sentinel skip in combined-pass re-check; fix mermaid routing R5-10: describe two-stage persist failure (fallback saves full payload) * fix(doctor): add envelope slack for token-aware truncation fallback R6 review: truncateAndSaveToFile's token-aware fallback returns the original content (sentinel-less) when the wrapped form would not be smaller, so the diagnostic's oversized check must tolerate that band. - Export TRUNCATION_FALLBACK_ENVELOPE_SLACK=500 from truncation.ts - Apply slack to the rawChars > 2x budget comparison - Adjust 4 test fixtures broken by the new threshold boundary - Fix 7 factual errors in design/E2E docs (mermaid, project-hash, web-search 102k, re-entrancy guard, shell/MCP bullet) - Add JSDoc caveat for MCP-disconnect limitation (R6-16) * docs: align §5 sentinel description with diagnostic code Bot R6-10 re-report: design doc §5 claimed three markers are skipped (prefix, in-body marker, <persisted-output> stub), but the diagnostic only checks two (prefix and <persisted-output> stub). Aligned the doc to match the code. The re-entrancy guard bullet still describes the scheduler's three-marker isAlreadyTruncated check, which is accurate. --------- Co-authored-by: 俊良 <[email protected]> Co-authored-by: Shaojin Wen <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Bounds tool-call output before it enters conversation history, mirroring Claude Code's three-layer model. (1) Single-result truncation: a per-tool or global character threshold spills oversized output to a temp file and hands the model a recoverable preview plus a
read_filepointer — media parts are preserved, a token-aware fallback ensures truncation never makes output larger, spilled files get0600perms, and a prefix-matched sentinel guards against double-truncation. (2) Per-message batch budget: when one batch of tool results collectively exceedstoolOutputBatchBudget(default 200k chars), the largest results are offloaded to disk, with a warning logged if it still can't get under budget. (3) Per-tool thresholds declared on each tool:shell30k,grep20k,read-fileself-managed,mcp500k,agent32k keeping the tail. Truncation runs centrally inCoreToolScheduler, deferring PostToolUse/skill metadata injection until after truncation so<system-reminder>envelopes are never bisected. Adds atoolOutputBatchBudgetsetting wired through both core and the CLI settings schema.Why it's needed
Large tool output — a shell command dumping 100KB+, a giant JSON, a many-line file read — currently flows verbatim into history and can blow past the model's input window; in the worst case the session gets permanently stuck re-sending an over-budget history. This centralizes and generalizes output bounding so every string-returning tool is capped before it reaches the model, while keeping the full output recoverable on disk. The per-tool thresholds let each tool declare a budget that fits its typical useful output instead of a one-size-fits-all cap.
Reviewer Test Plan
How to verify
Unit:
npm run test --workspace @qwen-code/qwen-code-core— the truncation and scheduler suites cover keep-direction, the token-aware fallback, per-tool budgets, the batch-budget offload,Part[]media preservation, deferred hook-metadata not being bisected, and the "self-managed tool exempt from the line cap" case. End-to-end (headlessnode dist/cli.js ... --openai-logging):read_fileis unchanged — itsmaxOutputChars: Infinityexemption means the scheduler never truncates it, so it keeps paginating through fileUtils as before (defaultlimit= 1000 lines with a "Showing lines 1-1000" header; an explicitlimitreturns the full content) — whilerun_shell_commandonseq 1 20000is bounded to a ~30k char-only preview and spilled to a*.outputtemp file.Evidence (Before & After)
Non-UI change; verified by an A/B of two real bundles (BEFORE =
origin/main, AFTER = this PR merged into the same main), driving headless runs against a mock provider that captures the exact tool results entering history.read_fileis unchanged across the A/B —origin/mainhas no scheduler-side truncation at all, so both builds page identically: default params return the first 1000 lines with a "Showing lines 1-1000 of 3001" header, and an explicitlimit: 3000returns the complete 13,940 chars. The behavior change is in shell:seq 1 20000goes from 6,389 chars on BEFORE (the global 1000-line cap bit first: head ~200 + tail ~800 lines) to 30,474 chars on AFTER (the 30k char-only budget: head 6,000 + tail 23,961, line cap no longer undercutting), carrying theTool output was too large and has been truncatedpointer and a0600*.outputspill file. Batch offload greedily spills the largest result to a0600preview;-1disables the budget.Tested on
Environment (optional)
npm run build && npm run bundle, then headlessnode dist/cli.jswith--openai-loggingagainst the configured provider; plus the core unit suites.Risk & Scope
CoreToolScheduleron the success path of every tool call (previously only shell and MCP truncated locally), and hook/skill metadata injection is deferred to after truncation — a moderate reordering covered by a dedicated test. Per-tool budgets are char-only so a self-managed tool (read-file) and a declared char budget (grep) are no longer undercut by the global line cap.toolOutputBatchBudgetsetting (default 200000;-1disables). Shell output truncation is now char-only (the 30k budget is no longer undercut by the global line cap) and keeps both head and tail instead of head-only. Noread_filebehavior change — itsmaxOutputChars: Infinityis a defensive exemption guaranteeing the new scheduler pass can never cap a self-managed (paginating) tool; read_file's pagination is identical to before.Linked Issues
Related to #4049 (large tool output overflowing the context window). This does not fully close it — the live context-usage indicator and compaction prompts requested there are out of scope here.
中文说明
这个 PR 做了什么
在工具调用输出进入对话历史之前对其收口，复刻 Claude Code 的三层模型。(1) 单结果截断：按 per-tool 或全局字符阈值，把超大输出落盘到临时文件，给模型一段可恢复的 preview 加
read_file指针——保留媒体 part，token 感知回退保证截断不会让输出反而更大，落盘文件用0600权限，并用 sentinel（按前缀匹配）防止重复截断。(2) per-message 批预算：一批工具结果总字符超过toolOutputBatchBudget（默认 200k）时，把最大的几个落盘；仍降不到预算下时记一条 warning。(3) 每个工具声明的 per-tool 阈值：shell30k、grep20k、read-file自管、mcp500k、agent32k 保留尾部。截断集中在CoreToolScheduler执行，并把 PostToolUse/skill metadata 的注入延后到截断之后，避免<system-reminder>被切断。新增toolOutputBatchBudget配置，core 和 CLI settings schema 都接通。为什么需要
大工具输出——dump 100KB+ 的 shell 命令、巨型 JSON、多行文件读取——目前会原样进入历史，可能撑爆模型输入窗口；最坏情况下会话会永久卡死在反复重发超额历史。本 PR 把输出收口集中化、通用化，让每个返回字符串的工具在到达模型前都被截断，同时完整输出在磁盘上可恢复。per-tool 阈值让每个工具按自身典型有用输出量声明预算，而不是一刀切。
Reviewer 测试计划
如何验证
单测：
npm run test --workspace @qwen-code/qwen-code-core——truncation 与 scheduler 套件覆盖了 keep 方向、token 感知回退、per-tool 预算、批预算 offload、Part[]媒体保留、延后的 hook metadata 不被切断、以及"自管工具豁免行数上限"这个 case。端到端（headlessnode dist/cli.js ... --openai-logging）：read_file行为不变——其maxOutputChars: Infinity豁免使 scheduler 永不截断它，仍按 fileUtils 分页（默认limit=1000 行带 "Showing lines 1-1000" header；显式limit返回完整内容）；而对seq 1 20000执行run_shell_command被收口成约 30k 的 char-only preview 并落盘到*.output临时文件。证据（Before & After）
非 UI 改动；通过两个真实 bundle 的 A/B 验证（BEFORE=
origin/main，AFTER=本 PR 干净合入同一 main），headless 跑 mock provider 捕获进入历史的工具结果。read_file在 A/B 两侧行为一致——origin/main根本没有 scheduler 侧截断，两个 build 分页相同：默认参数返回前 1000 行带 "Showing lines 1-1000 of 3001" header，显式limit: 3000返回完整 13,940 字符。行为变化在 shell：seq 1 20000从 BEFORE 的 6,389 字符（全局 1000 行上限先生效：head ~200 + tail ~800 行）变为 AFTER 的 30,474 字符（30k char-only 预算：head 6,000 + tail 23,961，行数上限不再 undercut），带Tool output was too large and has been truncated指针和0600*.output落盘文件。批预算 greedy 把最大结果落盘成0600preview；-1禁用。测试平台
见上方 OS 表（🍏 macOS 已测；🪟 Windows / 🐧 Linux 未测，交由 CI）。
运行环境（可选）
npm run build && npm run bundle，然后用 headlessnode dist/cli.js加--openai-logging跑配置好的 provider；外加 core 单测套件。风险与范围
CoreToolScheduler的每次工具调用成功路径上执行（之前只有 shell 和 MCP 在本地截断），且 hook/skill metadata 注入被延后到截断之后——这是一处中等规模的重排，有专门测试覆盖。per-tool 预算是 char-only，因此自管工具（read-file）和声明了字符预算的工具（grep）不再被全局行数上限 undercut。toolOutputBatchBudget配置（默认 200000，-1禁用）。shell 输出截断现在是 char-only（30k 预算不再被全局行数上限 undercut）且同时保留首尾，而非只保留 head。read_file行为无变化——其maxOutputChars: Infinity是防御性豁免，保证新 scheduler pass 永不 cap 自管（分页）工具；read_file 的分页与之前完全一致。