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:');