dsh-compaction-weave 0.0.0-stage → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/CHANGELOG.md +103 -0
  2. package/LICENSE +21 -0
  3. package/README.en.md +145 -0
  4. package/README.md +148 -2
  5. package/cordis.patch.yml +19 -0
  6. package/docs/architecture.md +84 -0
  7. package/docs/benchmarks/published-0.3.2-rc.1-tests.json +576 -0
  8. package/docs/benchmarks/rc2-documentation.json +41 -0
  9. package/docs/benchmarks/rc2-linux-tests.json +590 -0
  10. package/docs/benchmarks/rc2-live-and-cost.json +746 -0
  11. package/docs/benchmarks/rc3-host-compatibility.json +2314 -0
  12. package/docs/benchmarks/rc4-tests.json +617 -0
  13. package/docs/benchmarks/review35-compression.json +117 -0
  14. package/docs/benchmarks/v0.3.2-live-four-way.json +3495 -0
  15. package/docs/benchmarks/v0.3.2-tests.json +590 -0
  16. package/docs/configuration.md +131 -0
  17. package/docs/development.md +95 -0
  18. package/docs/en/architecture.md +75 -0
  19. package/docs/en/configuration.md +131 -0
  20. package/docs/en/development.md +92 -0
  21. package/docs/en/feedback.md +47 -0
  22. package/docs/en/principles.md +235 -0
  23. package/docs/en/testing.md +368 -0
  24. package/docs/en/troubleshooting.md +60 -0
  25. package/docs/feedback.md +47 -0
  26. package/docs/images/principles-context.en.svg +77 -0
  27. package/docs/images/principles-context.zh.svg +77 -0
  28. package/docs/images/principles-pipeline.en.svg +93 -0
  29. package/docs/images/principles-pipeline.zh.svg +93 -0
  30. package/docs/images/principles-recovery.en.svg +46 -0
  31. package/docs/images/principles-recovery.zh.svg +46 -0
  32. package/docs/principles.md +235 -0
  33. package/docs/test-results.json +634 -0
  34. package/docs/testing.md +358 -0
  35. package/docs/troubleshooting.md +60 -0
  36. package/lib/abort.js +13 -0
  37. package/lib/action-state.js +60 -0
  38. package/lib/atomic-replace.js +18 -0
  39. package/lib/attachments.js +76 -0
  40. package/lib/audit-reject.js +161 -0
  41. package/lib/audit.js +939 -0
  42. package/lib/cache-policy.js +71 -0
  43. package/lib/client.js +696 -0
  44. package/lib/command-compact.js +38 -0
  45. package/lib/command-heartbeat.js +61 -0
  46. package/lib/config.js +596 -0
  47. package/lib/constraint-scope.js +37 -0
  48. package/lib/continuation-budget.js +69 -0
  49. package/lib/continuation-pending.js +57 -0
  50. package/lib/continuation-progress.js +46 -0
  51. package/lib/continuation.js +287 -0
  52. package/lib/engine-entry.js +103 -0
  53. package/lib/engine.js +2485 -0
  54. package/lib/failure-diagnostics.js +220 -0
  55. package/lib/history-source.js +74 -0
  56. package/lib/history.js +712 -0
  57. package/lib/idle-compaction.js +64 -0
  58. package/lib/index.js +611 -0
  59. package/lib/instruction-source.js +163 -0
  60. package/lib/journal.js +164 -0
  61. package/lib/manual-error.js +179 -0
  62. package/lib/memory-policy.js +383 -0
  63. package/lib/meter.js +387 -0
  64. package/lib/observation-mask.js +390 -0
  65. package/lib/proactive.js +108 -0
  66. package/lib/progress-facts.js +347 -0
  67. package/lib/progress-state.js +30 -0
  68. package/lib/prompt.js +194 -0
  69. package/lib/reconstruct.js +72 -0
  70. package/lib/reference-input.js +107 -0
  71. package/lib/region.js +972 -0
  72. package/lib/source-provenance.js +58 -0
  73. package/lib/source-recovery.js +22 -0
  74. package/lib/source-refs.js +137 -0
  75. package/lib/state.js +46 -0
  76. package/lib/storage-path.js +42 -0
  77. package/lib/summary-budget.js +187 -0
  78. package/lib/summary-config.js +308 -0
  79. package/lib/summary-progress.js +56 -0
  80. package/lib/summary-retry.js +27 -0
  81. package/lib/summary-timeout.js +68 -0
  82. package/lib/summary.js +476 -0
  83. package/lib/tools.js +341 -0
  84. package/lib/transaction-host.js +252 -0
  85. package/lib/transaction.js +285 -0
  86. package/lib/validate.js +503 -0
  87. package/lib/version.js +3 -0
  88. package/lib/window.js +120 -0
  89. package/lib/work-report.js +55 -0
  90. package/locale/en.json +6 -0
  91. package/locale/zh.json +6 -0
  92. package/package.json +71 -4
package/lib/config.js ADDED
@@ -0,0 +1,596 @@
1
+ // 配置解析:既接受官方 BasicCompactionConfig 的键(方便迁移),也接受本插件扩展的键。
2
+ // 未知键不报错,只收集到 unknown 里由调用方决定是否告警——因为这一行的 config
3
+ // 可能来自别人(例如 bili 曾经往 compaction-basic 行写过 auto:false)。
4
+
5
+ export const DEFAULT_CONFIG = Object.freeze({
6
+ // ---- L2 触发 ----
7
+ auto: true,
8
+ idleCompactionMinutes: 0, // Independent of auto; 0 = disabled, checked on a new user turn only.
9
+ idleCompactionMinTokens: 0, // Minimum context tokens before idle resume triggers compaction; 0 = auto.
10
+ idleRetainTokens: 0, // Recent tail tokens preserved on idle resume compaction; 0 = full shrinkable prefix.
11
+ thresholdRatio: 0.8,
12
+ minimumReductionRatio: 0.2, // Target total-input reduction per automatic compaction.
13
+ headroomTokens: 33000, // Reserve room for the next response and tool results.
14
+ cachePreservePrefix: true,
15
+ cacheMaxCheckpoints: 4,
16
+ cacheMinSavingsTokens: 4096,
17
+ minGrowthTokens: 0, // 0 = 每次达线都压;>0 表示自上次压缩以来至少增长这么多才压
18
+
19
+ // ---- L1 窗口 ----
20
+ windowFallback: 200000,
21
+ windowClampMin: 65536,
22
+ // { "provider/model": 1234567 }
23
+ windowProviderMap: Object.freeze({}),
24
+
25
+ // ---- L3 摘要模型 ----
26
+ summarizationProvider: null,
27
+ summarizationModel: null,
28
+ maxTokens: 8192,
29
+ // Independent complete-request limits. Bytes are planning units, not provider tokens.
30
+ summaryInputRatio: 0.75,
31
+ summaryInputMaxBytes: 458752,
32
+ compactionRetries: 1,
33
+ summaryTimeoutMs: 180000,
34
+ summaryRetryCount: 2, // Additional attempts per unfinished summary/page, including corrective requests.
35
+ summaryRetryDelayMs: 1000, // Exponential delay between attempts, capped at 30 seconds.
36
+ language: 'auto', // 'auto' | 'zh' | 'en'
37
+
38
+ // ---- L5 保留 ----
39
+ retainRatio: 0.16,
40
+ retainTokens: null,
41
+ // Recent raw quotes are bounded and evicted oldest-first. Current requirements
42
+ // remain audited independently; all original events remain in verified archives.
43
+ preserveRecentMessages: 32,
44
+ preserveRecentUserTokens: 4096,
45
+
46
+ // ---- L6 溢出 ----
47
+ maxOverflowRetries: 1,
48
+ reactiveStep: 1,
49
+ maxSummaryChunks: 32, // Successful bounded chunks, separate from failure retries.
50
+
51
+ // ---- L7 失败 ----
52
+ failureThreshold: 3,
53
+
54
+ // ---- 附加 ----
55
+ proactiveEnabled: true,
56
+ proactiveMinTokens: 8192,
57
+ proactiveMinGrowthTokens: 4096,
58
+ continuationEnabled: true,
59
+ continuationMaxBytes: 98304,
60
+ continuationMemoryBytes: 12288, // Bounded working notes; exact requirements remain separate.
61
+ continuationMaxExtraCalls: 4, // Persistent extra-call allowance; only a new manual command may renew an exhausted budget.
62
+ archiveEnabled: true,
63
+ archiveDir: null,
64
+ observationMaskingEnabled: true,
65
+ observationMaskThresholdChars: 4000,
66
+ observationMaskHeadChars: 300,
67
+ observationMaskTailChars: 300,
68
+ auditEnabled: true,
69
+ auditCoverageThreshold: 0.6,
70
+ // ⚠️ 审计发现"约束行不见了"时,默认**中止这次压缩**,不是记条日志了事。
71
+ // 只 warn 的后果是:约束真的丢了,用户却看到压缩"成功",模型下一轮就按
72
+ // 缺了约束的摘要干活 —— 这种损失在对话里是静默的,事后根本追不回来。
73
+ // 可以显式关掉(`auditBlockOnLoss: false`)来换取"宁可压缩成功"的取舍,
74
+ // 但那是一个需要用户自己做的决定,不是默认行为。
75
+ auditBlockOnLoss: true,
76
+ strictHostFingerprints: false,
77
+ debug: false,
78
+ });
79
+
80
+ /** 官方 CompactionPolicyConfig 的键,原样接受。 */
81
+ const OFFICIAL_KEYS = new Set([
82
+ 'auto',
83
+ 'thresholdRatio',
84
+ 'headroomTokens',
85
+ 'retainRatio',
86
+ 'retainTokens',
87
+ 'summarizationProvider',
88
+ 'summarizationModel',
89
+ 'maxTokens',
90
+ 'compactionRetries',
91
+ 'maxOverflowRetries',
92
+ 'modelPolicies',
93
+ ]);
94
+
95
+ const KNOWN_KEYS = new Set([...OFFICIAL_KEYS, ...Object.keys(DEFAULT_CONFIG)]);
96
+
97
+ export const MAX_IDLE_COMPACTION_MINUTES = 30 * 24 * 60;
98
+
99
+ /** Never round or clamp an explicit idle interval. */
100
+ export function normalizeIdleCompactionMinutes(value = DEFAULT_CONFIG.idleCompactionMinutes) {
101
+ if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > MAX_IDLE_COMPACTION_MINUTES) {
102
+ throw new Error(`compaction-weave: idleCompactionMinutes must be an integer between 0 and ${MAX_IDLE_COMPACTION_MINUTES} (0 disables it)`);
103
+ }
104
+ return value;
105
+ }
106
+
107
+ function num(value, fallback, { min = -Infinity, max = Infinity, integer = false } = {}) {
108
+ if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
109
+ let v = integer ? Math.round(value) : value;
110
+ if (v < min) v = min;
111
+ if (v > max) v = max;
112
+ return v;
113
+ }
114
+
115
+ function bool(value, fallback) {
116
+ return typeof value === 'boolean' ? value : fallback;
117
+ }
118
+
119
+ /**
120
+ * 顶层 `maxTokens` 的归一化。
121
+ *
122
+ * ⚠️ 不能走 `num(..., { min: 256 })`:那个函数会把低于下限的输入**悄悄抬到下限**,
123
+ * 于是用户写 128 实际跑 256 —— 请求的输出上限被单方面改大,用户以为设生效了。
124
+ * 宿主对同名官方字段用的是 `assertPositiveInteger`(`value <= 0` 才拒,见
125
+ * `dsh-compaction-basic/lib/index.js:59-74`),显式正整数原样保留、非法值直接拒。
126
+ * 这里与宿主、也与本文件 `modelPolicies[].maxTokens`(下限 1)保持一致。
127
+ */
128
+ function normalizeMaxTokens(value, fallback) {
129
+ if (value === undefined || value === null) return fallback;
130
+ if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
131
+ throw new Error(`compaction-weave: maxTokens (${String(value)}) must be a positive integer`);
132
+ }
133
+ return value;
134
+ }
135
+
136
+ /** Positive quote budget; legacy zero is represented as null, which selection
137
+ * resolves to the automatic budget. No unlimited raw-memory mode is implicit. */
138
+ function optionalLimit(value, name, bounds) {
139
+ if (value === undefined || value === null || value === 0) return null;
140
+ if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value)) {
141
+ throw new Error(`compaction-weave: ${name} (${String(value)}) must be an integer or null`);
142
+ }
143
+ if (typeof bounds.min === 'number' && value < bounds.min) {
144
+ throw new Error(`compaction-weave: ${name} (${String(value)}) must be an integer >= ${bounds.min}`);
145
+ }
146
+ if (typeof bounds.max === 'number' && value > bounds.max) {
147
+ throw new Error(`compaction-weave: ${name} (${String(value)}) must be an integer <= ${bounds.max}`);
148
+ }
149
+ return value;
150
+ }
151
+
152
+ function str(value, fallback) {
153
+ return typeof value === 'string' && value.length > 0 ? value : fallback;
154
+ }
155
+
156
+ function ratio(value, fallback) {
157
+ return num(value, fallback, { min: 0.01, max: 0.99 });
158
+ }
159
+
160
+ function normalizeProviderMap(raw) {
161
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return Object.freeze({});
162
+ const out = {};
163
+ for (const [k, v] of Object.entries(raw)) {
164
+ const n = num(v, NaN, { min: 1, integer: true });
165
+ if (Number.isFinite(n)) out[k] = n;
166
+ }
167
+ return Object.freeze(out);
168
+ }
169
+
170
+ /**
171
+ * 单条 `modelPolicies` 允许出现的键(官方 `ModelCompactPolicyConfig` 的键集)。
172
+ * 注意这里**不含** `auto`:`auto` 只在顶层生效,出现在单条策略里属于拼错或误解。
173
+ */
174
+ const MODEL_POLICY_KEYS = new Set([
175
+ 'provider',
176
+ 'model',
177
+ 'thresholdRatio',
178
+ 'headroomTokens',
179
+ 'retainRatio',
180
+ 'retainTokens',
181
+ 'summarizationProvider',
182
+ 'summarizationModel',
183
+ 'maxTokens',
184
+ 'compactionRetries',
185
+ 'maxOverflowRetries',
186
+ ]);
187
+
188
+ // 宿主的合法区间是**开区间下端** `(0, 1]`(`assertRatio`:`value <= 0 || value > 1` 才拒)。
189
+ // 接受 0 的后果不是"保守一点",而是 `thresholdRatio: 0` 会让压缩线落在 0 —— 永远不触发;
190
+ // `retainRatio: 0` 则会在保留量校验里与 0 阈值直接冲突。
191
+ function assertRatio(name, value) {
192
+ if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
193
+ throw new Error(`compaction-weave: ${name} must be a number in (0, 1]`);
194
+ }
195
+ }
196
+
197
+ function assertInteger(name, value, min) {
198
+ if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value) || value < min) {
199
+ throw new Error(`compaction-weave: ${name} must be an integer >= ${min}`);
200
+ }
201
+ }
202
+
203
+ /**
204
+ * 官方 `modelPolicies` 的归一化与校验。
205
+ *
206
+ * ⚠️ 这里**必须抛错而不是静默丢弃**。静默丢弃的失败模式是:用户写了一条覆盖
207
+ * 策略,插件照常启动、日志一切正常,但那条策略从来没生效过 —— 用户只会觉得
208
+ * "这个插件不听话"。宿主自己的 `resolveModelPolicies` / `assertModelPolicy` /
209
+ * `validatePolicy` 在加载期就抛,我们保持同一语义。
210
+ *
211
+ * 校验项与宿主一致:
212
+ * - 每条必须是对象,只允许官方键集(未知键 = 拼错)
213
+ * - `provider` / `model` 必须是非空字符串
214
+ * - 同一 `provider/model` 不允许出现两次(后一条永远命中不到,属于静默失效)
215
+ * - `retainRatio` 与 `retainTokens` 互斥(同时给时哪一个赢没有直觉答案)
216
+ * - `summarizationProvider` / `summarizationModel` 必须成对
217
+ *
218
+ * @param {unknown} raw
219
+ * @returns {ReadonlyArray<Readonly<Record<string, any>>>}
220
+ */
221
+ function normalizeModelPolicies(raw) {
222
+ if (raw === undefined || raw === null) return Object.freeze([]);
223
+ if (!Array.isArray(raw)) {
224
+ throw new Error('compaction-weave: modelPolicies must be an array');
225
+ }
226
+ const seen = new Set();
227
+ const out = [];
228
+ for (let index = 0; index < raw.length; index += 1) {
229
+ const name = `modelPolicies[${index}]`;
230
+ const item = raw[index];
231
+ if (!item || typeof item !== 'object' || Array.isArray(item)) {
232
+ throw new Error(`compaction-weave: ${name} must be an object`);
233
+ }
234
+ for (const key of Object.keys(item)) {
235
+ if (!MODEL_POLICY_KEYS.has(key)) {
236
+ throw new Error(`compaction-weave: ${name}: unknown key "${key}"`);
237
+ }
238
+ }
239
+ const provider = item.provider;
240
+ const model = item.model;
241
+ if (typeof provider !== 'string' || provider.length === 0) {
242
+ throw new Error(`compaction-weave: ${name}.provider must be a non-empty string`);
243
+ }
244
+ if (typeof model !== 'string' || model.length === 0) {
245
+ throw new Error(`compaction-weave: ${name}.model must be a non-empty string`);
246
+ }
247
+ const key = `${provider}/${model}`;
248
+ if (seen.has(key)) {
249
+ throw new Error(`compaction-weave: duplicate model policy for ${key}`);
250
+ }
251
+ seen.add(key);
252
+
253
+ const policy = { provider, model };
254
+ if (item.thresholdRatio !== undefined) {
255
+ assertRatio(`${name}.thresholdRatio`, item.thresholdRatio);
256
+ policy.thresholdRatio = item.thresholdRatio;
257
+ }
258
+ if (item.headroomTokens !== undefined) {
259
+ assertInteger(`${name}.headroomTokens`, item.headroomTokens, 0);
260
+ policy.headroomTokens = item.headroomTokens;
261
+ }
262
+ if (item.retainRatio !== undefined && item.retainTokens !== undefined) {
263
+ throw new Error(`compaction-weave: ${name}: retainRatio and retainTokens are mutually exclusive`);
264
+ }
265
+ if (item.retainRatio !== undefined) {
266
+ assertRatio(`${name}.retainRatio`, item.retainRatio);
267
+ policy.retainRatio = item.retainRatio;
268
+ }
269
+ if (item.retainTokens !== undefined) {
270
+ assertInteger(`${name}.retainTokens`, item.retainTokens, 0);
271
+ policy.retainTokens = item.retainTokens;
272
+ }
273
+ if (item.maxTokens !== undefined) {
274
+ // 宿主只要求正整数(`assertPositiveInteger`:`value <= 0` 才拒)。
275
+ // 这里卡 256 会拒掉宿主合法的 1–255,而 `normalizeModelPolicies` 在
276
+ // `apply()` 阶段抛错 = 整行引擎加载失败,用户只是给某个模型配了个小输出上限。
277
+ assertInteger(`${name}.maxTokens`, item.maxTokens, 1);
278
+ policy.maxTokens = item.maxTokens;
279
+ }
280
+ if (item.compactionRetries !== undefined) {
281
+ assertInteger(`${name}.compactionRetries`, item.compactionRetries, 0);
282
+ policy.compactionRetries = item.compactionRetries;
283
+ }
284
+ if (item.maxOverflowRetries !== undefined) {
285
+ assertInteger(`${name}.maxOverflowRetries`, item.maxOverflowRetries, 0);
286
+ policy.maxOverflowRetries = item.maxOverflowRetries;
287
+ }
288
+ const sumProvider = item.summarizationProvider;
289
+ const sumModel = item.summarizationModel;
290
+ if (sumProvider !== undefined || sumModel !== undefined) {
291
+ if (
292
+ typeof sumProvider !== 'string' ||
293
+ typeof sumModel !== 'string' ||
294
+ (sumProvider.length === 0) !== (sumModel.length === 0)
295
+ ) {
296
+ throw new Error(
297
+ `compaction-weave: ${name}: summarizationProvider and summarizationModel must be set together as an empty or non-empty pair`,
298
+ );
299
+ }
300
+ policy.summarizationProvider = sumProvider;
301
+ policy.summarizationModel = sumModel;
302
+ }
303
+ out.push(Object.freeze(policy));
304
+ }
305
+ return Object.freeze(out);
306
+ }
307
+
308
+ /**
309
+ * 逐条策略在**与全局默认合并之后**再校验一次保留量。
310
+ *
311
+ * 只看单条字段的类型是不够的:`{thresholdRatio: 0.2}` 这条策略自己完全合法,
312
+ * 但配上全局 `retainRatio: 0.3` 就成了"保留区比压缩线还大"。这种组合在加载期
313
+ * 是查不出来的 —— 要等到真的命中这个模型、真的去算 spec 时才抛
314
+ * `retainTokens (…) must be less than threshold tokens …`,而那时摘要请求一次都
315
+ * 没发出去。用户看到的是"配了个策略,从此这个模型再也不压缩"。
316
+ *
317
+ * 官方的 `validateRatioRetention` 就是在 `resolveConfig` 里对每条 policy 做完
318
+ * 合并后校验的(`dsh-compaction-basic/lib/index.js:220-235`)。
319
+ *
320
+ * 绝对 token 数(`retainTokens`)与窗口大小有关,容量无关阶段判不了,留给
321
+ * `resolveCompactSpec` 的运行时检查。
322
+ *
323
+ * @param {ReadonlyArray<Record<string, any>>} policies
324
+ * @param {Record<string, any>} config 已归一化、已兜底的全局配置
325
+ */
326
+ function validateModelPolicyRetention(policies, config) {
327
+ if (policies.length === 0) return;
328
+ const baseThreshold = config.thresholdRatio;
329
+ const baseRetainTokens = config.retainTokens === null ? undefined : config.retainTokens;
330
+ const baseRetainRatio = baseRetainTokens === undefined ? config.retainRatio : undefined;
331
+ for (let index = 0; index < policies.length; index += 1) {
332
+ const policy = policies[index];
333
+ const name = `modelPolicies[${index}]`;
334
+ const thresholdRatio = policy.thresholdRatio ?? baseThreshold;
335
+ // 与官方 `resolveRetention` 的互斥继承一致:目标给了 retainTokens 就只看它,
336
+ // 给了 retainRatio 就用它,都没给才继承全局。
337
+ let retainRatio;
338
+ let retainTokens;
339
+ if (policy.retainTokens !== undefined) {
340
+ retainTokens = policy.retainTokens;
341
+ } else if (policy.retainRatio !== undefined) {
342
+ retainRatio = policy.retainRatio;
343
+ } else {
344
+ retainTokens = baseRetainTokens;
345
+ retainRatio = baseRetainRatio;
346
+ }
347
+ if (retainTokens !== undefined) continue;
348
+ if (retainRatio !== undefined && retainRatio >= thresholdRatio) {
349
+ throw new Error(
350
+ `compaction-weave: ${name}: retainRatio (${retainRatio}) must be less than the resolved thresholdRatio (${thresholdRatio})`,
351
+ );
352
+ }
353
+ }
354
+ }
355
+
356
+ /**
357
+ * @param {Record<string, unknown>|undefined} raw
358
+ * @returns {{ config: Readonly<Record<string, any>>, unknown: string[] }}
359
+ */
360
+ export function resolveConfig(raw) {
361
+ const input = raw && typeof raw === 'object' ? raw : {};
362
+ const unknown = [];
363
+ for (const key of Object.keys(input)) {
364
+ if (!KNOWN_KEYS.has(key)) unknown.push(key);
365
+ }
366
+
367
+ // 顶层同样适用官方的保留量互斥规则(`validatePolicy` 对默认值和覆盖项一视同仁)。
368
+ // 默认配置里 `retainTokens` 是 null("没设"),所以只有用户真的给了数字才算冲突。
369
+ if (input.retainRatio !== undefined && input.retainTokens !== undefined && input.retainTokens !== null) {
370
+ throw new Error('compaction-weave: retainRatio and retainTokens are mutually exclusive');
371
+ }
372
+
373
+ const modelPolicies = normalizeModelPolicies(input.modelPolicies);
374
+
375
+ const config = {
376
+ auto: bool(input.auto, DEFAULT_CONFIG.auto),
377
+ idleCompactionMinutes: normalizeIdleCompactionMinutes(input.idleCompactionMinutes),
378
+ idleCompactionMinTokens: num(input.idleCompactionMinTokens, DEFAULT_CONFIG.idleCompactionMinTokens, { min: 0, integer: true }),
379
+ idleRetainTokens: num(input.idleRetainTokens, DEFAULT_CONFIG.idleRetainTokens, { min: 0, integer: true }),
380
+ proactiveEnabled: input.proactiveEnabled !== false,
381
+ proactiveMinTokens: num(input.proactiveMinTokens, DEFAULT_CONFIG.proactiveMinTokens, {min:1024,integer:true}),
382
+ proactiveMinGrowthTokens: num(input.proactiveMinGrowthTokens, DEFAULT_CONFIG.proactiveMinGrowthTokens, {min:512,integer:true}),
383
+ continuationEnabled: bool(input.continuationEnabled, DEFAULT_CONFIG.continuationEnabled),
384
+ continuationMaxBytes: num(input.continuationMaxBytes, DEFAULT_CONFIG.continuationMaxBytes, { min: 4096, max: 262144, integer: true }),
385
+ continuationMemoryBytes: num(input.continuationMemoryBytes, DEFAULT_CONFIG.continuationMemoryBytes, { min: 2048, max: 24576, integer: true }),
386
+ continuationMaxExtraCalls: num(input.continuationMaxExtraCalls, DEFAULT_CONFIG.continuationMaxExtraCalls, { min: 0, max: 32, integer: true }),
387
+ thresholdRatio: ratio(input.thresholdRatio, DEFAULT_CONFIG.thresholdRatio),
388
+ minimumReductionRatio: num(input.minimumReductionRatio, DEFAULT_CONFIG.minimumReductionRatio, { min: 0.05, max: 0.9 }),
389
+ headroomTokens: num(input.headroomTokens, DEFAULT_CONFIG.headroomTokens, {
390
+ min: 0,
391
+ integer: true,
392
+ }),
393
+ minGrowthTokens: num(input.minGrowthTokens, DEFAULT_CONFIG.minGrowthTokens, {
394
+ min: 0,
395
+ integer: true,
396
+ }),
397
+
398
+ windowFallback: num(input.windowFallback, DEFAULT_CONFIG.windowFallback, {
399
+ min: 1024,
400
+ integer: true,
401
+ }),
402
+ windowClampMin: num(input.windowClampMin, DEFAULT_CONFIG.windowClampMin, {
403
+ min: 1024,
404
+ integer: true,
405
+ }),
406
+ windowProviderMap: normalizeProviderMap(input.windowProviderMap),
407
+
408
+ summarizationProvider: str(input.summarizationProvider, null),
409
+ summarizationModel: str(input.summarizationModel, null),
410
+ maxTokens: normalizeMaxTokens(input.maxTokens, DEFAULT_CONFIG.maxTokens),
411
+ summaryInputRatio: num(input.summaryInputRatio, DEFAULT_CONFIG.summaryInputRatio, { min: 0.05, max: 1 }),
412
+ summaryInputMaxBytes: num(input.summaryInputMaxBytes, DEFAULT_CONFIG.summaryInputMaxBytes, { min: 4096, max: 16777216, integer: true }),
413
+ compactionRetries: num(input.compactionRetries, DEFAULT_CONFIG.compactionRetries, {
414
+ min: 0,
415
+ max: 8,
416
+ integer: true,
417
+ }),
418
+ summaryRetryCount: num(input.summaryRetryCount, DEFAULT_CONFIG.summaryRetryCount, {min:0,max:4,integer:true}),
419
+ summaryRetryDelayMs: num(input.summaryRetryDelayMs, DEFAULT_CONFIG.summaryRetryDelayMs, {min:0,max:30000,integer:true}),
420
+ summaryTimeoutMs: num(input.summaryTimeoutMs, DEFAULT_CONFIG.summaryTimeoutMs, {
421
+ min: 5000,
422
+ integer: true,
423
+ }),
424
+ language: ['auto', 'zh', 'en'].includes(input.language) ? input.language : 'auto',
425
+
426
+ retainRatio: ratio(input.retainRatio, DEFAULT_CONFIG.retainRatio),
427
+ retainTokens:
428
+ typeof input.retainTokens === 'number' && Number.isFinite(input.retainTokens)
429
+ ? num(input.retainTokens, null, { min: 0, integer: true })
430
+ : null,
431
+ // 旧配置 0 使用自动预算并记录迁移警告。原话超预算按最旧优先归档;
432
+ // 仍有效的要求独立审计,不能随原话预算被静默删除。
433
+ preserveRecentMessages: optionalLimit(input.preserveRecentMessages ?? DEFAULT_CONFIG.preserveRecentMessages, 'preserveRecentMessages', {
434
+ min: 1,
435
+ max: 100000,
436
+ integer: true,
437
+ }),
438
+ preserveRecentUserTokens: optionalLimit(input.preserveRecentUserTokens ?? DEFAULT_CONFIG.preserveRecentUserTokens, 'preserveRecentUserTokens', {
439
+ min: 1,
440
+ integer: true,
441
+ }),
442
+
443
+ maxOverflowRetries: num(input.maxOverflowRetries, DEFAULT_CONFIG.maxOverflowRetries, {
444
+ min: 0,
445
+ max: 8,
446
+ integer: true,
447
+ }),
448
+ reactiveStep: num(input.reactiveStep, DEFAULT_CONFIG.reactiveStep, {
449
+ min: 1,
450
+ max: 8,
451
+ integer: true,
452
+ }),
453
+
454
+ failureThreshold: num(input.failureThreshold, DEFAULT_CONFIG.failureThreshold, {
455
+ min: 1,
456
+ max: 20,
457
+ integer: true,
458
+ }),
459
+
460
+ maxSummaryChunks: num(input.maxSummaryChunks, DEFAULT_CONFIG.maxSummaryChunks, { min: 1, max: 128, integer: true }),
461
+
462
+ cachePreservePrefix: bool(input.cachePreservePrefix, DEFAULT_CONFIG.cachePreservePrefix),
463
+ cacheMaxCheckpoints: num(input.cacheMaxCheckpoints, DEFAULT_CONFIG.cacheMaxCheckpoints, {min:1,max:8,integer:true}),
464
+ cacheMinSavingsTokens: num(input.cacheMinSavingsTokens, DEFAULT_CONFIG.cacheMinSavingsTokens, {min:1024,integer:true}),
465
+ archiveEnabled: bool(input.archiveEnabled, DEFAULT_CONFIG.archiveEnabled),
466
+ archiveDir: str(input.archiveDir, null),
467
+ observationMaskingEnabled: bool(input.observationMaskingEnabled, DEFAULT_CONFIG.observationMaskingEnabled),
468
+ observationMaskThresholdChars: num(input.observationMaskThresholdChars, DEFAULT_CONFIG.observationMaskThresholdChars, { min: 128, integer: true }),
469
+ observationMaskHeadChars: num(input.observationMaskHeadChars, DEFAULT_CONFIG.observationMaskHeadChars, { min: 0, max: 4096, integer: true }),
470
+ observationMaskTailChars: num(input.observationMaskTailChars, DEFAULT_CONFIG.observationMaskTailChars, { min: 0, max: 4096, integer: true }),
471
+ auditEnabled: bool(input.auditEnabled, DEFAULT_CONFIG.auditEnabled),
472
+ auditCoverageThreshold: num(
473
+ input.auditCoverageThreshold,
474
+ DEFAULT_CONFIG.auditCoverageThreshold,
475
+ { min: 0, max: 1 },
476
+ ),
477
+ auditBlockOnLoss: bool(input.auditBlockOnLoss, DEFAULT_CONFIG.auditBlockOnLoss),
478
+ strictHostFingerprints: bool(input.strictHostFingerprints, DEFAULT_CONFIG.strictHostFingerprints),
479
+ debug: bool(input.debug, DEFAULT_CONFIG.debug),
480
+
481
+ // 官方按 provider/model 的覆盖策略。这里必须**保留**它(而不是收下就扔),
482
+ // 由 `resolveTargetPolicy` 在解析出真实路由后再合并。
483
+ modelPolicies,
484
+ };
485
+
486
+ // retainRatio 必须小于 thresholdRatio,否则保留区比压缩线还大,永远压不动。
487
+ if (config.retainRatio >= config.thresholdRatio) {
488
+ config.retainRatio = Math.max(0.05, Math.min(0.5, config.thresholdRatio * 0.5));
489
+ }
490
+ // headroomTokens 不能吃掉整个窗口。
491
+ if (config.headroomTokens >= config.windowFallback) {
492
+ config.headroomTokens = Math.floor(config.windowFallback / 4);
493
+ }
494
+
495
+ // 全局兜底之后,再逐条校验"目标覆盖 + 全局继承"合并出来的保留量。
496
+ // 必须在兜底**之后**做:否则拿还没修正的全局值去比,会误报。
497
+ validateModelPolicyRetention(config.modelPolicies, config);
498
+
499
+ return { config: Object.freeze(config), unknown, migrations: ['preserveRecentMessages', 'preserveRecentUserTokens'].filter(key => input[key] === 0).map(key => `${key}=0 migrated to the automatic recent-quote budget`) };
500
+ }
501
+
502
+ /**
503
+ * 官方 resolveCompactSpec 的等价实现。
504
+ * @param {{thresholdRatio:number, headroomTokens:number, retainRatio:number, retainTokens:number|null}} policy
505
+ * @param {number} contextWindow
506
+ * @param {number} reservedCompletionTokens
507
+ */
508
+ export function resolveCompactSpec(policy, contextWindow, reservedCompletionTokens) {
509
+ const messageBudgetTokens = contextWindow - reservedCompletionTokens;
510
+ if (messageBudgetTokens <= 0) {
511
+ throw new Error(
512
+ `compaction-weave: contextWindow ${contextWindow} leaves no message budget after reserving ${reservedCompletionTokens} completion tokens`,
513
+ );
514
+ }
515
+ // ⚠️ headroom 大于整条消息预算时**不能抛错**。
516
+ // 32000 级的小窗口配上默认 33000 headroom 是真实配置(不是用户写错),
517
+ // 抛错等于"自动压缩永不触发",而恰恰是这种小窗口最容易撞上供应商的
518
+ // 上下文上限。这里的语义是"提前量",不是"硬性门槛":提前量超过窗口
519
+ // 本身时就按窗口的四分之一收敛,压缩线仍然严格早于阻断线。
520
+ const effectiveHeadroom =
521
+ policy.headroomTokens >= messageBudgetTokens
522
+ ? Math.floor(messageBudgetTokens * 0.25)
523
+ : policy.headroomTokens;
524
+ const pressureBudgetTokens = messageBudgetTokens - effectiveHeadroom;
525
+ const thresholdTokens = Math.floor(
526
+ Math.min(contextWindow * policy.thresholdRatio, pressureBudgetTokens),
527
+ );
528
+ const retainTokens =
529
+ policy.retainTokens ?? Math.floor(messageBudgetTokens * policy.retainRatio);
530
+ if (retainTokens >= thresholdTokens) {
531
+ throw new Error(
532
+ `compaction-weave: retainTokens (${retainTokens}) must be less than threshold tokens ${thresholdTokens}`,
533
+ );
534
+ }
535
+ // 官方 `resolveCompactSpec` 会把重试次数、输出上限一并带进 spec
536
+ // (`dsh-compaction-basic/lib/index.js:135-145`)。调用方读的是 spec 上的
537
+ // `compactionRetries`,如果这里不返回,`spec.compactionRetries + 1` 就是 NaN,
538
+ // `while (attempts < NaN)` 一次都不跑 —— 表现为"两种触发都返回 null,
539
+ // 一次压缩都没发生",但日志里一切正常。
540
+ return {
541
+ contextWindow,
542
+ messageBudgetTokens,
543
+ pressureBudgetTokens,
544
+ thresholdTokens,
545
+ retainTokens,
546
+ maxTokens: policy.maxTokens,
547
+ compactionRetries: policy.compactionRetries,
548
+ maxOverflowRetries: policy.maxOverflowRetries,
549
+ };
550
+ }
551
+
552
+ /**
553
+ * 按 provider/model 找官方 `modelPolicies` 里的覆盖项,并合并到基础配置上。
554
+ *
555
+ * 官方语义(`ModelCompactPolicyConfig`):`{provider, model, ...CompactionPolicyConfig}`,
556
+ * 精确匹配 provider+model,命中后覆盖阈值、保留量、摘要模型、输出上限、重试次数。
557
+ * 收进"已知键"却不使用等于静默丢弃 —— 比报错更糟,因为用户会以为配置生效了。
558
+ *
559
+ * ⚠️ 保留量**不能简单浅合并**。`resolveCompactSpec` 里是
560
+ * `policy.retainTokens ?? Math.floor(messageBudget * policy.retainRatio)`,
561
+ * `retainTokens` 优先级更高。全局配了 `retainTokens: 1000`、目标只想改成
562
+ * `retainRatio: 0.3` 时,浅合并会留下全局的 1000,目标的 0.3 永远读不到 ——
563
+ * 用户改了个"能生效"的键,实际一点没变。
564
+ *
565
+ * 官方 `resolveRetention(config, fallback)` 的规则是:目标给了 `retainTokens`
566
+ * 就用它,给了 `retainRatio` 就用比例,都没给才继承全局;并且两者互斥。
567
+ * 所以合并时必须**把另一个键抹掉**,不能只覆盖。
568
+ *
569
+ * @param {Readonly<Record<string, any>>} config
570
+ * @param {string|undefined} provider
571
+ * @param {string|undefined} model
572
+ * @returns {Readonly<Record<string, any>>}
573
+ */
574
+ export function resolveTargetPolicy(config, provider, model) {
575
+ const policies = config.modelPolicies;
576
+ if (!Array.isArray(policies) || policies.length === 0) return config;
577
+ for (const policy of policies) {
578
+ if (!policy || typeof policy !== 'object') continue;
579
+ if (policy.provider !== provider || policy.model !== model) continue;
580
+ const merged = { ...config };
581
+ for (const key of Object.keys(policy)) {
582
+ if (key === 'provider' || key === 'model') continue;
583
+ if (policy[key] === undefined) continue;
584
+ merged[key] = policy[key];
585
+ }
586
+ // 保留量按官方 `resolveRetention` 的互斥语义收口:目标选了其中一种,
587
+ // 另一种就必须从合并结果里消失,否则全局那个会一直赢。
588
+ if (policy.retainTokens !== undefined) {
589
+ delete merged.retainRatio;
590
+ } else if (policy.retainRatio !== undefined) {
591
+ delete merged.retainTokens;
592
+ }
593
+ return merged;
594
+ }
595
+ return config;
596
+ }
@@ -0,0 +1,37 @@
1
+ import {auditCompaction} from './audit.js';
2
+ import {isReferenceContextKind,sourceKindOf} from './source-provenance.js';
3
+ import {blocksToText} from './meter.js';
4
+
5
+ // Tool evidence is useful for facts, never proof of a new user permission.
6
+ // Read immutable event identities directly; a generated checkpoint's claimed
7
+ // source seq/kind cannot upgrade its text to an authoritative user instruction.
8
+ export function collectReferenceMessages(session, seqs) {
9
+ const seen=new Set(),references=[],pending=[...seqs].reverse();
10
+ while(pending.length) {
11
+ const seq=pending.pop();
12
+ if(!Number.isSafeInteger(seq)||seen.has(seq))continue;
13
+ seen.add(seq);
14
+ const event=session.eventAt(seq);
15
+ if(!event)continue;
16
+ if(event.type==='tool/result'||isReferenceContextKind(sourceKindOf(session,seq))) {
17
+ const message=session.deriveEventMessage(event);
18
+ const text=typeof message?.content==='string'?message.content:blocksToText(message?.content);
19
+ if(text)references.push({seq,text});
20
+ }
21
+ // Edges are durable host-event metadata, not a generated notes field.
22
+ // Follow only earlier events so malformed cycles cannot enlarge traversal.
23
+ const parents=[...event.sourceEventSeqs??[],...(event.type==='compaction/summary'?event.data?.shadowedSeqs??[]:[])];
24
+ for(let index=parents.length-1;index>=0;index--)if(parents[index]<seq)pending.push(parents[index]);
25
+ }
26
+ return references;
27
+ }
28
+
29
+ // Requirements outside the replacement span stay visible in their original
30
+ // messages. They need no duplicate quote in the new checkpoint, but generated
31
+ // notes must still respect their polarity, values, conditions and object scope.
32
+ export function auditMemorySelection({selection,...options}) {
33
+ const local=new Set(selection.active.map(message=>message.seq));
34
+ const userMessages=[...selection.active,...selection.retained??[]].sort((a,b)=>a.seq-b.seq);
35
+ const report=auditCompaction({...options,userMessages});
36
+ return {...report,lost:report.lost.filter(item=>item.reason!=='coverage'||local.has(item.seq))};
37
+ }