From 35769d00d9cccf4f89b24fd1b096bdd5ce8bb5c5 Mon Sep 17 00:00:00 2001 From: haelyra <49814733+haelyra@users.noreply.github.com> Date: Thu, 29 Oct 2026 19:42:27 -0700 Subject: [PATCH] fix(context): validate budgets and remind before native compaction Reject numeric prefixes, fractions and unsafe window integers consistently with summary scheduling while preserving resolver precedence. Cap only the default context reminder at eighty percent of a valid earlier native compaction budget; explicit thresholds, including zero, retain their intentional policy. Document the independent capacity, summary and advisory contracts. RED controls reproduce malformed-budget summary triggers and the known-1M/native-200k missed reminder. Resolver65, helper47, actualStop18 and actualPreToolUse54 pass on Node18 and24. Parent and independent reviewer approved the exact diff before commit. Registry rebinding remains the integration coordinator responsibility after combining documentation repairs. --- scripts/lib/transcript-context.js | 19 +++++++--- skills/strategic-compact/SKILL.md | 6 +-- tests/hooks/session-end.test.js | 24 ++++++++++++ tests/hooks/suggest-compact.test.js | 32 ++++++++++++++++ tests/lib/llm-summary.test.js | 4 ++ tests/lib/transcript-context.test.js | 55 ++++++++++++++++++++++++++++ 6 files changed, 131 insertions(+), 9 deletions(-) diff --git a/scripts/lib/transcript-context.js b/scripts/lib/transcript-context.js index fd7397bf6..5d77b20b9 100644 --- a/scripts/lib/transcript-context.js +++ b/scripts/lib/transcript-context.js @@ -144,8 +144,8 @@ function resolveContextWindow(tokens, model) { // Explicit window override wins: 400k models (e.g. Opus 4.x) match neither the // 200k default nor the 1M marker and would otherwise report ~double usage (#2290). - const explicitWindow = Number.parseInt(env.ECC_CONTEXT_WINDOW_TOKENS || '', 10); - if (Number.isInteger(explicitWindow) && explicitWindow > 0) { + const explicitWindow = Number(env.ECC_CONTEXT_WINDOW_TOKENS || ''); + if (Number.isSafeInteger(explicitWindow) && explicitWindow > 0) { return { windowTokens: explicitWindow, inferred: false }; } @@ -170,8 +170,8 @@ function resolveContextWindow(tokens, model) { // trigger point (e.g. 786432 on a 1M-window model), not the context window // size. Honor it only as a last-resort fallback so it cannot mask the [1m] // marker, known large-window families, or >200k observed tokens above. - const autoCompactWindow = Number.parseInt(env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || '', 10); - if (Number.isInteger(autoCompactWindow) && autoCompactWindow > 0) { + const autoCompactWindow = Number(env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || ''); + if (Number.isSafeInteger(autoCompactWindow) && autoCompactWindow > 0) { return { windowTokens: autoCompactWindow, inferred: false }; } @@ -203,7 +203,8 @@ function isContextWindowInferred(tokens, model) { /** * Resolve the context-size suggestion threshold (tokens). * `COMPACT_CONTEXT_THRESHOLD=0` disables the context signal entirely; - * other invalid values fall back to the window-scaled default. + * other invalid values fall back to the window-scaled default, capped at + * 80 percent of a valid native compaction budget when that is earlier. */ function resolveContextThreshold(env, windowTokens) { const raw = env && env.COMPACT_CONTEXT_THRESHOLD; @@ -217,7 +218,13 @@ function resolveContextThreshold(env, windowTokens) { } } - return windowTokens >= LARGE_CONTEXT_WINDOW_TOKENS ? DEFAULT_CONTEXT_THRESHOLD_LARGE : DEFAULT_CONTEXT_THRESHOLD_STANDARD; + const defaultThreshold = windowTokens >= LARGE_CONTEXT_WINDOW_TOKENS ? DEFAULT_CONTEXT_THRESHOLD_LARGE : DEFAULT_CONTEXT_THRESHOLD_STANDARD; + const nativeBudget = Number(env && env.CLAUDE_CODE_AUTO_COMPACT_WINDOW); + if (!Number.isSafeInteger(nativeBudget) || nativeBudget <= 0) return defaultThreshold; + // Keep the standard 160k/200k headroom before native compaction, without + // changing model-capacity evidence or an explicit reminder policy above. + const nativeThreshold = Math.max(1, Math.floor(nativeBudget * (DEFAULT_CONTEXT_THRESHOLD_STANDARD / STANDARD_CONTEXT_WINDOW_TOKENS))); + return Math.min(defaultThreshold, nativeThreshold); } /** diff --git a/skills/strategic-compact/SKILL.md b/skills/strategic-compact/SKILL.md index e998a772b..52dccf6bd 100644 --- a/skills/strategic-compact/SKILL.md +++ b/skills/strategic-compact/SKILL.md @@ -33,7 +33,7 @@ Strategic compaction at logical boundaries: The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and combines two signals: -1. **Context size (primary)** — Reads the latest `usage` record from the session transcript (`transcript_path` in the hook payload) and sums `input_tokens + cache_read_input_tokens + cache_creation_input_tokens` (the true context size of the turn). Suggests `/compact` at a window-scaled threshold — 160k tokens on a 200k window, 250k on a 1M window (detected from a `[1m]` model marker, or inferred when observed tokens already exceed 200k) — and re-reminds after every additional 60k tokens of context growth +1. **Context size (primary)** — Reads the latest `usage` record from the session transcript (`transcript_path` in the hook payload) and sums `input_tokens + cache_read_input_tokens + cache_creation_input_tokens` (the true context size of the turn). Suggests `/compact` at a window-scaled threshold — 160k tokens on a 200k window, 250k on a 1M window (detected from a `[1m]` model marker, or inferred when observed tokens already exceed 200k) — and re-reminds after every additional 60k tokens of context growth. A valid native compaction budget can lower the default reminder threshold to 80% of that budget; model-capacity percentages still use the resolved model window 2. **Tool-call count (secondary)** — Counts tool invocations in session; suggests at a configurable threshold (default: 50 calls), then every 25 calls after Tool count alone is a weak proxy for window pressure: a few large file reads or MCP responses can fill the window in very few calls, while many tiny calls can cross 50 with a near-empty window. The context-size signal fires when it actually matters. @@ -65,7 +65,7 @@ Tool count alone is a weak proxy for window pressure: a few large file reads or Environment variables: - `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50) -- `COMPACT_CONTEXT_THRESHOLD` — Context tokens before the context-size suggestion (default: 160000 on a 200k window, 250000 on a 1M window; `0` disables the context signal) +- `COMPACT_CONTEXT_THRESHOLD` — Context tokens before the context-size suggestion (default: 160000 on a 200k window, 250000 on a 1M window, capped at 80% of a valid native compaction budget when earlier). An explicit positive threshold overrides that default cap; `0` disables the context signal. - `COMPACT_CONTEXT_INTERVAL` — Additional context tokens before the suggestion repeats (default: 60000) - `COMPACT_STATE_TTL_DAYS` — Days before stale per-session state files in the temp dir are swept (default: 14) - `ECC_CONTEXT_WINDOW_TOKENS` — Explicit context-window size, in tokens, overriding auto-detection. Set this for large-window models whose reported id lacks a `[1m]` marker (e.g. 400k Opus 4.x, or a new 1M-window model family) so the threshold scales to the real window instead of defaulting to 200k and overstating context usage. @@ -73,7 +73,7 @@ Environment variables: > Window precedence is: `ECC_CONTEXT_WINDOW_TOKENS`, then the `[1m]` marker, a known large-window model family, observed tokens above 200k, the native auto-compact fallback, and finally the inferred 200k default. Set `ECC_CONTEXT_WINDOW_TOKENS` when you know the actual window and automatic detection lacks that information; do not treat the native compact trigger as proof of model capacity. -The Stop-hook summary scheduler protects resume state before compaction. It uses the earlier of confirmed capacity and a valid native compaction budget. When capacity is inferred, it uses only a valid native budget, or treats the remaining budget as unknown if none is provided. This scheduling boundary does not change model-capacity resolution or the `/compact` suggestion threshold. +The Stop-hook summary scheduler protects resume state before compaction. It uses the earlier of confirmed capacity and a valid native compaction budget. When capacity is inferred, it uses only a valid native budget, or treats the remaining budget as unknown if none is provided. Model-capacity resolution remains separate. The default `/compact` reminder threshold independently uses the earlier of its window-scaled default and 80% of a valid native compaction budget. An explicit `COMPACT_CONTEXT_THRESHOLD`, including `0`, remains authoritative. ## Compaction Decision Guide diff --git a/tests/hooks/session-end.test.js b/tests/hooks/session-end.test.js index 05557aa80..927a2da07 100644 --- a/tests/hooks/session-end.test.js +++ b/tests/hooks/session-end.test.js @@ -291,6 +291,30 @@ function runTests() { }) ? passed++ : failed++); } + for (const nativeBudget of ['200000tokens', '200000.5', '9007199254740992']) { + (test(`invalid native budget ${nativeBudget} does not trigger a summary from inferred capacity`, () => { + const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-invalid-budget-')); + try { + const uuid = '12345678-1234-4234-8234-123456789abc'; + const transcript = path.join(home, `${uuid}.jsonl`); + fs.writeFileSync(transcript, [ + JSON.stringify({ type: 'user', content: 'Retain mechanical resume state with an invalid budget' }), + JSON.stringify({ type: 'assistant', message: { model: 'unknown-model', content: [], usage: { input_tokens: 180000 } } }), + ].join('\n') + '\n'); + const res = runHook(home, transcript, { + ECC_CONTEXT_WINDOW_TOKENS: '', CLAUDE_CODE_AUTO_COMPACT_WINDOW: nativeBudget, + ECC_LLM_SUMMARY_INTERVAL: '50', ECC_LLM_SUMMARY_CONTEXT_THRESHOLD: '20', + ECC_HOOK_DEADLINE_MS: '1', ECC_SKIP_LLM_SUMMARY: '', ECC_LLM_SUMMARY_SUBPROCESS: '', + }); + assert.strictEqual(res.status, 0, res.stderr); + assert.doesNotMatch(res.stderr, /LLM summary triggered/); + assert.match(fs.readFileSync(sessionFileFor(home, uuid), 'utf8'), /Retain mechanical resume state with an invalid budget/); + } finally { + fs.rmSync(home, { recursive: true, force: true }); + } + }) ? passed++ : failed++); + } + (test('logs an explicit LLM disable as skipped and persists mechanical resume state', () => { const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-session-skip-')); try { diff --git a/tests/hooks/suggest-compact.test.js b/tests/hooks/suggest-compact.test.js index bb25a372e..5a5892e1b 100644 --- a/tests/hooks/suggest-compact.test.js +++ b/tests/hooks/suggest-compact.test.js @@ -853,6 +853,38 @@ function runTests() { })) passed++; else failed++; + for (const [label, nativeBudget, explicitThreshold, shouldRemind] of [ + ['a smaller valid native budget caps the default reminder', '200000', '', true], + ['a malformed native budget does not cap the default reminder', '200000tokens', '', false], + ['a fractional native budget does not cap the default reminder', '200000.5', '', false], + ['an unsafe native integer does not cap the default reminder', '9007199254740992', '', false], + ['a larger native budget cannot enlarge the default reminder', '2000000', '', false], + ['an explicit later threshold remains intentional policy', '200000', '250000', false], + ['an explicit earlier threshold remains intentional policy', '200000', '100000', true], + ['an explicit zero still disables the context reminder', '200000', '0', false], + ]) { + if (test(label, () => { + const ctx = createContextContext(); + const transcript = writeTranscriptFixture(180000, 'claude-opus-4-5[1m]'); + try { + const result = runCompactWithInput( + { session_id: ctx.sessionId, transcript_path: transcript }, + { CLAUDE_CODE_AUTO_COMPACT_WINDOW: nativeBudget, COMPACT_CONTEXT_THRESHOLD: explicitThreshold, COMPACT_THRESHOLD: '50' }, + ); + assert.strictEqual(result.code, 0, result.stderr); + if (shouldRemind) { + assert.ok(result.stdout.includes('18% of 1M window'), `Keep capacity truthful while warning before compaction: ${result.stdout}`); + } else { + assert.strictEqual(result.stdout.trim(), '', `No default or tool-count reminder expected: ${result.stdout}`); + } + } finally { + fs.unlinkSync(transcript); + ctx.cleanup(); + } + })) passed++; + else failed++; + } + if (test('treats >200k observed tokens as a 1M window even without the [1m] marker', () => { const ctx = createContextContext(); const transcript = writeTranscriptFixture(230000, 'claude-opus-4-5'); diff --git a/tests/lib/llm-summary.test.js b/tests/lib/llm-summary.test.js index 00ac1693d..514ccedac 100644 --- a/tests/lib/llm-summary.test.js +++ b/tests/lib/llm-summary.test.js @@ -186,6 +186,10 @@ for (const [label, model, nativeBudget, explicitWindow, expected, tokens = 33000 ['native 786k compaction receives a timely summary on a 1M model', 'claude-opus-4-5[1m]', '786432', '', 10, 710000], ['confirmed capacity remains usable without a native budget', 'claude-opus-4-5[1m]', '', '', 67], ['known model family also respects the earlier native budget', 'claude-fable-5', '400000', '', 18], + ['unknown capacity rejects a numeric native prefix', 'unknown-model', '200000tokens', '', null, 180000], + ['unknown capacity rejects a fractional native budget', 'unknown-model', '200000.5', '', null, 180000], + ['unknown capacity rejects an unsafe native integer', 'unknown-model', '9007199254740992', '', null, 180000], + ['invalid explicit prefix does not override a valid native budget', 'unknown-model', '400000', '200000tokens', 55, 180000], ]) { test(label, () => { const keys = ['ECC_CONTEXT_WINDOW_TOKENS', 'CLAUDE_CODE_AUTO_COMPACT_WINDOW']; diff --git a/tests/lib/transcript-context.test.js b/tests/lib/transcript-context.test.js index b582aece1..cbfddfdc8 100644 --- a/tests/lib/transcript-context.test.js +++ b/tests/lib/transcript-context.test.js @@ -316,6 +316,40 @@ for (const [label, tokens, model, explicitWindow, expectedWindow, inferred] of [ }); } +// Window settings must use the same whole-number validation as the summary +// scheduler; a numeric prefix is not evidence of confirmed model capacity. +for (const invalid of ['200000tokens', '200000.5', '9007199254740992', 'Infinity', '1e309', '0', '-1']) { + test(`rejects malformed or unsafe window setting ${invalid} without changing precedence`, () => { + const previousExplicit = process.env.ECC_CONTEXT_WINDOW_TOKENS; + const previousNative = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW; + try { + process.env.ECC_CONTEXT_WINDOW_TOKENS = ''; + process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = invalid; + assert.deepStrictEqual(resolveContextWindow(180000, 'unknown-model'), { + windowTokens: STANDARD_CONTEXT_WINDOW_TOKENS, inferred: true, + }); + process.env.ECC_CONTEXT_WINDOW_TOKENS = invalid; + process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = '400000'; + assert.deepStrictEqual(resolveContextWindow(180000, 'unknown-model'), { + windowTokens: 400000, inferred: false, + }); + assert.deepStrictEqual(resolveContextWindow(180000, 'claude-opus-4-5[1m]'), { + windowTokens: LARGE_CONTEXT_WINDOW_TOKENS, inferred: false, + }); + process.env.ECC_CONTEXT_WINDOW_TOKENS = '400000'; + process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = invalid; + assert.deepStrictEqual(resolveContextWindow(180000, 'claude-opus-4-5[1m]'), { + windowTokens: 400000, inferred: false, + }); + } finally { + if (previousExplicit === undefined) delete process.env.ECC_CONTEXT_WINDOW_TOKENS; + else process.env.ECC_CONTEXT_WINDOW_TOKENS = previousExplicit; + if (previousNative === undefined) delete process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW; + else process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = previousNative; + } + }); +} + // ── isContextWindowInferred ── console.log('\nisContextWindowInferred:'); @@ -374,6 +408,27 @@ test('invalid COMPACT_CONTEXT_THRESHOLD falls back to the default', () => { } }); +test('caps only the default reminder at 80 percent of a valid native budget', () => { + assert.strictEqual(resolveContextThreshold({ CLAUDE_CODE_AUTO_COMPACT_WINDOW: '200000' }, LARGE_CONTEXT_WINDOW_TOKENS), 160000); + assert.strictEqual(resolveContextThreshold({ CLAUDE_CODE_AUTO_COMPACT_WINDOW: '100000' }, STANDARD_CONTEXT_WINDOW_TOKENS), 80000); + assert.strictEqual(resolveContextThreshold({ CLAUDE_CODE_AUTO_COMPACT_WINDOW: '2000000' }, LARGE_CONTEXT_WINDOW_TOKENS), DEFAULT_CONTEXT_THRESHOLD_LARGE); + assert.strictEqual(resolveContextThreshold({ CLAUDE_CODE_AUTO_COMPACT_WINDOW: '1' }, LARGE_CONTEXT_WINDOW_TOKENS), 1); +}); + +test('native reminder budget never overrides explicit threshold policy or disable', () => { + for (const threshold of ['0', '100000', '250000']) { + assert.strictEqual(resolveContextThreshold({ + CLAUDE_CODE_AUTO_COMPACT_WINDOW: '200000', COMPACT_CONTEXT_THRESHOLD: threshold, + }, LARGE_CONTEXT_WINDOW_TOKENS), Number(threshold)); + } +}); + +test('malformed or unsafe native budgets do not cap the default reminder', () => { + for (const invalid of ['200000tokens', '200000.5', '9007199254740992', 'Infinity', '0', '-1']) { + assert.strictEqual(resolveContextThreshold({ CLAUDE_CODE_AUTO_COMPACT_WINDOW: invalid }, LARGE_CONTEXT_WINDOW_TOKENS), DEFAULT_CONTEXT_THRESHOLD_LARGE); + } +}); + // ── resolveContextInterval ── console.log('\nresolveContextInterval:');