feat: add retainRatio and retainTokens settings for compaction budget management

Author: qorzj

docs/configuration.md

@@ -29,6 +29,8 @@ Deep Code 使用 `settings.json` 设置文件进行持久化配置，支持两
 | `env`                | object    | 环境变量分组（见下方子字段表）                                       |
 | `contextWindow`     | number/string | 上下文窗口上限，可使用精确 token 数或 `128K`、`1M` 等格式          |
 | `autoCompactWindow` | number/string | 自动压缩阈值，默认取上下文窗口的 80%                           |
+| `retainRatio` | number | 上下文压缩后，按模型上下文窗口的百分比保留最近对话历史的比例（默认 `0.16`，即 16%） |
+| `retainTokens` | number | 上下文压缩后，按绝对 token 数量保留最近对话历史的预算，与 `retainRatio` 互斥 |
 | `model`              | string    | 模型名称。优先级高于 `env.MODEL`                                    |
 | `thinkingEnabled`    | boolean   | 是否启用思考模式（DeepSeek V4 系列默认启用）                         |
 | `reasoningEffort`    | string    | 推理强度，可选 `"low"`、`"high"` 或 `"max"`（默认 `"max"`）        |
@@ -75,7 +77,24 @@ Deep Code 使用 `settings.json` 设置文件进行持久化配置，支持两
 }
 ```
 
-普通模型的默认上下文窗口为 `256K`，DeepSeek V4 系列为 `1M`。未设置自动压缩阈值时取最终上下文窗口的 50%；无效值会被忽略，自动压缩阈值超过上下文窗口时会限制为上下文窗口。
+普通模型的默认上下文窗口为 `256K`，DeepSeek V4 系列为 `1M`。未设置自动压缩阈值时取最终上下文窗口的 80%；无效值会被忽略，自动压缩阈值超过上下文窗口时会限制为上下文窗口。
+
+#### 压缩后的尾部保留预算
+
+`retainRatio` 和 `retainTokens` 是 `settings.json` 的顶层字段，同一配置文件只能设置其中一项。项目级设置任一项时，整体覆盖用户级的保留策略；项目未设置时继承用户配置，两处均未设置时默认采用 `retainRatio: 0.16`。
+
+`retainRatio` 必须是 `(0, 1]` 范围内的数字，预算按「上下文窗口减去输出预留」乘以该比例并向下取整。`retainTokens` 必须是非负整数，`0` 表示不额外预留尾部；不支持 `"32K"` 等字符串。
+
+最终保留预算必须严格小于实际生效的自动压缩阈值，否则报配置错误，不会自动缩小预算。使用较低阈值时，可能需要同时设置较小的保留预算：
+
+```json
+{
+  "autoCompactWindow": "180K",
+  "retainTokens": 32768
+}
+```
+
+这两项配置用于自动压缩。工具调用与结果会保持完整，因此实际保留量可能超过预算。手动压缩和上下文超限恢复继续采用不额外预留尾部的策略。
 
 #### `thinkingEnabled` — 思考模式
 

docs/configuration_en.md

@@ -29,6 +29,8 @@ The following are all the top-level fields supported in `settings.json`, along w
 | `env`              | object  | Group of environment variables (see sub-field table below)                 |
 | `contextWindow`   | number/string | Context-window limit as an exact token count or `128K`/`1M` value   |
 | `autoCompactWindow` | number/string | Auto-compaction threshold; defaults to 80% of the context window |
+| `retainRatio` | number | Budget for retaining recent conversation history after compaction, expressed as a fraction of the model's context window (default `0.16`, or 16%) |
+| `retainTokens` | number | Budget for retaining recent conversation history after compaction, expressed as an absolute token count; mutually exclusive with `retainRatio` |
 | `model`            | string  | Model name. Takes precedence over `env.MODEL`                              |
 | `thinkingEnabled`  | boolean | Whether to enable thinking mode (enabled by default for DeepSeek V4 series)|
 | `reasoningEffort`  | string  | Reasoning intensity: `"low"`, `"high"`, or `"max"` (default `"max"`)    |
@@ -75,7 +77,24 @@ The following are all the top-level fields supported in `settings.json`, along w
 }
 ```
 
-The default context window is `256K` for regular models and `1M` for DeepSeek V4 models. If the auto-compaction threshold is omitted, it is 50% of the final context window. Invalid values are ignored, and an auto-compaction threshold larger than the context window is capped at the context window.
+The default context window is `256K` for regular models and `1M` for DeepSeek V4 models. If the auto-compaction threshold is omitted, it is 80% of the final context window. Invalid values are ignored, and an auto-compaction threshold larger than the context window is capped at the context window.
+
+#### Compaction retention
+
+`retainRatio` and `retainTokens` are top-level `settings.json` fields. Set at most one per configuration file. A project-level setting replaces the user-level retention choice; otherwise, the user setting is inherited. With neither set, `retainRatio` defaults to `0.16`.
+
+`retainRatio` must be a number in `(0, 1]`. Its budget is the context window minus the output reserve, multiplied by the ratio and rounded down. `retainTokens` must be a non-negative integer; `0` requests no extra tail retention. Strings such as `"32K"` are not supported.
+
+The resulting budget must be strictly below the effective auto-compaction threshold. Invalid configurations produce an error rather than silently reducing the retention budget. A low threshold may require an explicit smaller retention budget:
+
+```json
+{
+  "autoCompactWindow": "180K",
+  "retainTokens": 32768
+}
+```
+
+These settings apply to automatic compaction. Tool calls and their results stay together, so the retained tail may exceed the budget. Manual compaction and context-overflow recovery continue to use no extra tail retention.
 
 #### `thinkingEnabled` — Thinking Mode
 

packages/core/src/common/compaction.ts

@@ -8,12 +8,33 @@ export type CompactBudget = {
   retain: number;
 };
 
-export function compactBudget(window: number, configuredThreshold = Math.floor(window * 0.8)): CompactBudget {
+export type CompactRetention = { retainRatio?: number; retainTokens?: number };
+
+export function validateCompactRetention({ retainRatio, retainTokens }: CompactRetention): void {
+  if (retainRatio !== undefined && retainTokens !== undefined)
+    throw new Error("retainRatio and retainTokens are mutually exclusive.");
+  if (retainRatio !== undefined && (!Number.isFinite(retainRatio) || retainRatio <= 0 || retainRatio > 1))
+    throw new Error("retainRatio must be a number in (0, 1].");
+  if (retainTokens !== undefined && (!Number.isInteger(retainTokens) || retainTokens < 0))
+    throw new Error("retainTokens must be a non-negative integer.");
+}
+
+export function compactBudget(
+  window: number,
+  configuredThreshold = Math.floor(window * 0.8),
+  retention: CompactRetention = {}
+): CompactBudget {
+  validateCompactRetention(retention);
   const output = Math.max(1, Math.min(65536, Math.floor(window / 8)));
   const input = window - output;
   const threshold = Math.min(configuredThreshold, input - output);
   if (threshold <= 0) throw new Error("The context window leaves no room for conversation input.");
-  return { output, input, threshold, retain: Math.min(Math.floor(input * 0.16), Math.floor(threshold * 0.8)) };
+  const retain = retention.retainTokens ?? Math.floor(input * (retention.retainRatio ?? 0.16));
+  if (retain >= threshold)
+    throw new Error(
+      `The retention budget (${retain}) must be less than the compaction threshold (${threshold}). Adjust retainRatio or retainTokens.`
+    );
+  return { output, input, threshold, retain };
 }
 
 /** An estimate, not a tokenizer. Never charge binary image encodings as text. */

packages/core/src/session.ts

@@ -387,6 +387,8 @@ export type SessionManagerOptions = {
     maxRequestFilesBytes?: number;
     contextWindow?: number;
     autoCompactWindow?: number;
+    retainRatio?: number;
+    retainTokens?: number;
     webSearchTool?: string;
     mcpServers?: Record<string, McpServerConfig>;
     permissions?: Required<PermissionSettings>;
@@ -436,6 +438,8 @@ export class SessionManager {
     maxRequestFilesBytes?: number;
     contextWindow?: number;
     autoCompactWindow?: number;
+    retainRatio?: number;
+    retainTokens?: number;
     webSearchTool?: string;
     mcpServers?: Record<string, McpServerConfig>;
     permissions?: Required<PermissionSettings>;
@@ -1914,7 +1918,11 @@ ${agentInstructions}
 
   private getCompactionBudget(model: string) {
     const settings = this.getResolvedSettings();
-    return compactBudget(settings.contextWindow ?? getDefaultContextWindow(model), settings.autoCompactWindow);
+    return compactBudget(
+      settings.contextWindow ?? getDefaultContextWindow(model),
+      settings.autoCompactWindow,
+      settings
+    );
   }
 
   /** Derive exactly the content used by both normal and summary requests, before uploads. */
@@ -1956,7 +1964,7 @@ ${agentInstructions}
       anchor?.route === route &&
       anchor.hashes.length <= hashes.length &&
       anchor.hashes.every((hash, index) => hash === hashes[index]);
-    const tokens = anchored ? Math.max(estimate, anchor.tokens + estimate - anchor.estimate) : estimate;
+    const tokens = anchored ? anchor.tokens + estimate - anchor.estimate : estimate;
     return { route, hashes, estimate, tokens };
   }
 
@@ -2048,10 +2056,10 @@ ${agentInstructions}
         const promptTokens = response.usage?.prompt_tokens;
         this.requestUsageAnchors.set(sessionId, {
           ...measurement,
-          tokens: Math.max(
-            measurement.estimate,
-            typeof promptTokens === "number" ? promptTokens : measurement.estimate
-          ),
+          tokens:
+            typeof promptTokens === "number" && Number.isFinite(promptTokens) && promptTokens >= 0
+              ? promptTokens
+              : measurement.estimate,
         });
         return response;
       } catch (error) {

packages/core/src/settings.ts

@@ -2,6 +2,7 @@ import { DEEPSEEK_V4_MODELS, defaultsToThinkingMode, type MultimodalMode } from
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import { compactBudget, validateCompactRetention } from "./common/compaction";
 
 export type DeepcodingEnv = Record<string, string | undefined> & {
   MODEL?: string;
@@ -88,6 +89,8 @@ export type DeepcodingSettings = {
   env?: DeepcodingEnv;
   contextWindow?: number | string;
   autoCompactWindow?: number | string;
+  retainRatio?: number;
+  retainTokens?: number;
   model?: string;
   temperature?: number;
   thinkingEnabled?: boolean;
@@ -116,6 +119,8 @@ export type ResolvedDeepcodingSettings = {
   model: string;
   contextWindow: number;
   autoCompactWindow: number;
+  retainRatio?: number;
+  retainTokens?: number;
   temperature?: number;
   thinkingEnabled: boolean;
   reasoningEffort: ReasoningEffort;
@@ -607,6 +612,15 @@ export function resolveSettingsSources(
   );
   const defaultAutoCompactWindow = Math.max(1, Math.floor(contextWindow * 0.8));
   const autoCompactWindow = Math.min(configuredAutoCompactWindow ?? defaultAutoCompactWindow, contextWindow);
+  validateCompactRetention(userSettings ?? {});
+  validateCompactRetention(projectSettings ?? {});
+  const retention =
+    projectSettings?.retainRatio !== undefined || projectSettings?.retainTokens !== undefined
+      ? projectSettings
+      : userSettings;
+  const retainTokens = retention?.retainTokens;
+  const retainRatio = retainTokens === undefined ? (retention?.retainRatio ?? 0.16) : undefined;
+  compactBudget(contextWindow, autoCompactWindow, { retainRatio, retainTokens });
 
   const thinkingEnabled =
     parseBoolean(systemEnv.THINKING_ENABLED) ??
@@ -705,6 +719,8 @@ export function resolveSettingsSources(
     model,
     contextWindow,
     autoCompactWindow,
+    retainRatio,
+    retainTokens,
     temperature,
     thinkingEnabled,
     reasoningEffort,

packages/core/src/tests/compaction.test.ts

@@ -55,7 +55,12 @@ function fixture(history: SessionMessage[], respond: (request: any, call: number
   process.env.HOME = root;
   process.env.USERPROFILE = root;
   const requests: any[] = [];
-  const settings = { model: "test-vision", contextWindow: 256 * 1024, autoCompactWindow: 190000 };
+  const settings = {
+    model: "test-vision",
+    contextWindow: 256 * 1024,
+    autoCompactWindow: 190000,
+    retainTokens: undefined as number | undefined,
+  };
   const manager = new SessionManager({
     projectRoot: root,
     createOpenAIClient: () => ({
@@ -539,3 +544,66 @@ test("summary requests share Files API upload and expired-reference recovery", a
   assert.match(JSON.stringify(f.requests[1].messages), /file-2/);
   assert.doesNotMatch(JSON.stringify(f.requests[1].messages), /base64/);
 });
+
+test("retention budgets use the input window and reject budgets at the effective threshold", () => {
+  assert.equal(compactBudget(1048576, 184320).retain, 157286);
+  assert.equal(compactBudget(100000, 50000, { retainRatio: 0.2 }).retain, 17500);
+  assert.equal(compactBudget(100000, 50000, { retainTokens: 1234 }).retain, 1234);
+  assert.equal(compactBudget(100000, 50000, { retainTokens: 0 }).retain, 0);
+  for (const retainTokens of [50000, 50001])
+    assert.throws(() => compactBudget(100000, 50000, { retainTokens }), /must be less/);
+  assert.throws(() => compactBudget(100000, 10000), /must be less/);
+  assert.throws(() => compactBudget(100000, 100000, { retainTokens: 75000 }), /must be less/);
+});
+
+test("actual usage calibrates image-heavy history downward while new images and text still count", async () => {
+  const images = Array.from({ length: 26 }, (_, i) => ({
+    type: "image_url",
+    image_url: { url: `data:image/png;base64,${i}` },
+  }));
+  const f = fixture([{ ...message("images"), contentParams: images }], () => ({
+    ...answer(),
+    usage: { prompt_tokens: 70106 },
+  }));
+  await f.run();
+  const context = await f.internal.prepareContext(f.read(), f.settings.model, true);
+  const measured = f.internal.measureRequest("compact-test", context.messages, f.settings.model);
+  assert.ok(measured.estimate > 100000);
+  assert.equal(measured.tokens, 70106);
+  const added = { ...message("new", "user", "new observations ".repeat(1000)), contentParams: images.slice(0, 1) };
+  f.internal.saveSessionMessages("compact-test", [...f.read(), added]);
+  const next = await f.internal.prepareContext(f.read(), f.settings.model, true);
+  const nextMeasurement = f.internal.measureRequest("compact-test", next.messages, f.settings.model);
+  assert.equal(nextMeasurement.tokens, 70106 + nextMeasurement.estimate - measured.estimate);
+  assert.ok(nextMeasurement.tokens > 70106 + 4096);
+  f.settings.autoCompactWindow = 100000;
+  await f.run();
+  assert.equal(f.requests.length, 2);
+  assert.ok(f.requests.every((request) => request.tool_choice !== "none"));
+});
+
+test("missing or invalid actual usage falls back to estimates, while zero is valid", async () => {
+  for (const prompt_tokens of [undefined, NaN, Infinity, -1, "4000", 0]) {
+    const f = fixture([message("old")], () => ({ ...answer(), usage: { prompt_tokens } }));
+    await f.run();
+    const context = await f.internal.prepareContext(f.read(), f.settings.model, true);
+    const measured = f.internal.measureRequest("compact-test", context.messages, f.settings.model);
+    assert.equal(measured.tokens, prompt_tokens === 0 ? 0 : measured.estimate);
+  }
+});
+
+test("automatic compaction honors the configured tail budget", async () => {
+  const retained: number[] = [];
+  for (const retainTokens of [7000, 20000]) {
+    const history = Array.from({ length: 10 }, (_, i) => message(`history-${i}`, "user", "x".repeat(20000)));
+    const f = fixture(history);
+    f.settings.contextWindow = 100000;
+    f.settings.autoCompactWindow = 50000;
+    f.settings.retainTokens = retainTokens;
+    await f.run();
+    assert.equal(f.requests.length, 2);
+    assert.equal(f.requests[0].tool_choice, "none");
+    retained.push(f.read().filter((m) => !m.compacted && !m.meta?.isSummary).length);
+  }
+  assert.deepEqual(retained, [2, 4]);
+});

packages/core/src/tests/settings-and-notify.test.ts

@@ -256,6 +256,7 @@ test("resolveSettings parses numeric and K/M context window settings", () => {
     {
       contextWindow: " 2m ",
       autoCompactWindow: 300_000,
+      retainTokens: 32000,
     },
     { model: "default-model", baseURL: "https://default.example.com" },
     TEST_PROCESS_ENV
@@ -936,3 +937,36 @@ test("PLUS settings normalize subscriptionPlan and keep it separate from env", (
     fs.rmSync(tempDir, { recursive: true, force: true });
   }
 });
+
+test("retention settings default and override as a pair across configuration sources", () => {
+  const resolve = (user: any, project: any = {}) =>
+    resolveSettingsSources(user, project, { model: "test", baseURL: "https://example.com" }, {});
+  assert.equal(resolve({}).retainRatio, 0.16);
+  assert.equal(resolve({}).retainTokens, undefined);
+  const absolute = resolve({ retainRatio: 0.2 }, { retainTokens: 0 });
+  assert.equal(absolute.retainTokens, 0);
+  assert.equal(absolute.retainRatio, undefined);
+  const ratio = resolve({ retainTokens: 1000 }, { retainRatio: 0.1 });
+  assert.equal(ratio.retainRatio, 0.1);
+  assert.equal(ratio.retainTokens, undefined);
+  assert.equal(resolve({ retainTokens: 1000 }).retainTokens, 1000);
+  assert.equal(resolve({ retainRatio: 0.2 }).retainRatio, 0.2);
+});
+
+test("retention settings reject conflicting, invalid and oversized budgets", () => {
+  const resolve = (user: any, project: any = {}) =>
+    resolveSettingsSources(user, project, { model: "test", baseURL: "https://example.com" }, {});
+  const conflict = { retainRatio: 0.16, retainTokens: 1000 };
+  assert.throws(() => resolve(conflict, { retainTokens: 2000 }), /mutually exclusive/);
+  assert.throws(() => resolve({}, conflict), /mutually exclusive/);
+  for (const retainRatio of [0, -1, 1.1, Infinity, NaN, "0.16", null])
+    assert.throws(() => resolve({ retainRatio }), /retainRatio/);
+  for (const retainTokens of [-1, 1.5, Infinity, NaN, "32K", null])
+    assert.throws(() => resolve({}, { retainTokens }), /retainTokens/);
+  assert.throws(() => resolve({ contextWindow: 100000, autoCompactWindow: 10000 }), /must be less/);
+  assert.throws(
+    () => resolve({ contextWindow: 100000, autoCompactWindow: 50000, retainTokens: 50000 }),
+    /must be less/
+  );
+  assert.throws(() => resolve({ retainRatio: 1 }), /must be less/);
+});