/** * Context compaction: heuristic fallback + optional one-shot LLM summary. * * Tool schemas are reserved out of historyBudget. Compact against conversation * tokens only — never treat a large tool list as "history is full". */ const truncate = require('./truncate.js'); const CHAR_PER_TOKEN = 3; const THRESHOLD = 0.68; const MIN_SUMMARY = 80; const MIN_COMPACT_MESSAGES = 4; const COMPACT_PROMPT = 'Summarize this coding-agent conversation. Use exactly these sections:\n' + '1. Goal\n' + '2. Done\n' + '3. Files / decisions\n' + '4. Open work\n' + '5. Next action\n' + 'Be specific (paths, names, errors). Do not say the conversation was compacted.'; const VOICE_COMPACT_PROMPT = 'Summarize this spoken assistant conversation for the next turn. Use exactly these sections:\n' + '1. Latest user request\n' + '2. Facts from tools\n' + '3. What was already answered\n' + '4. Open follow-ups, original goal, user preferences and corrections\n' + 'Be specific. Do not greet. Do not say the conversation was compacted.'; function contentChars(content) { if (content == null) return 0; if (typeof content === 'string') return content.length; if (Array.isArray(content)) { let n = 0; for (let i = 0; i < content.length; i++) { const p = content[i]; if (p == null) continue; if (typeof p === 'string') n += p.length; else if (p.text) n += String(p.text).length; else if (p.type === 'image_url' || p.image_url) n += 1600; else n += JSON.stringify(p).length; } return n; } return JSON.stringify(content).length; } function messageChars(m) { if (!m) return 0; let n = contentChars(m.content); if (m.tool_calls) n += JSON.stringify(m.tool_calls).length; if (m.name) n += String(m.name).length; return n + 8; } function nonSystemCount(messages) { let n = 0; for (const m of messages || []) { if (m && m.role !== 'system') n += 1; } return n; } function conversationTokens(messages) { let n = 0; for (const m of messages || []) n += messageChars(m); return Math.ceil(n / CHAR_PER_TOKEN); } function toolTokens(tools) { return Math.ceil(JSON.stringify(tools || []).length / CHAR_PER_TOKEN); } function estimateTokens(messages, tools) { return conversationTokens(messages) + toolTokens(tools); } function historyBudget(ctxSize, tools, attempt, extraTokens = 0) { const cap = ctxSize > 0 ? Number(ctxSize) : 8192; const toolTok = toolTokens(tools); const reserve = Math.max(384, Math.floor(cap * (0.18 + (Number(attempt) || 0) * 0.08))); return Math.max(240, Math.floor(cap * 0.72) - toolTok - reserve - extraTokens); } function shouldCompact(messages, tools, ctxSize, extraTokens = 0) { const budget = historyBudget(ctxSize, tools, 0, extraTokens); const tokens = conversationTokens(messages); // Large first requests or tool results can overflow before four messages. // A small greeting must not be discarded merely because schemas are large. return tokens > budget && (nonSystemCount(messages) >= MIN_COMPACT_MESSAGES || conversationTokens((messages || []).filter((m) => m.role !== 'system')) > 1024); } function isOverflowError(err) { const s = String((err && err.message) || err || ''); return /context window|context.?length|too many tokens|maximum context|prompt too (?:long|large)|prompt exceeds|ContextOverflow|reduce the prompt size/i.test( s ); } function usage(messages, tools, ctxSize) { return snapshot(estimateTokens(messages, tools), ctxSize); } function snapshot(used, ctxSize) { const limit = ctxSize > 0 ? Number(ctxSize) : 8192; const n = Math.max(0, Math.round(Number(used) || 0)); const pct = limit ? Math.min(100, Math.round((n / limit) * 1000) / 10) : 0; return { used: n, limit, pct, threshold: Math.round(THRESHOLD * 100), over: n > Math.floor(limit * THRESHOLD), }; } function isDegenerate(summary) { const s = String(summary || '').trim(); if (s.length < MIN_SUMMARY) return true; if (/conversation compacted/i.test(s)) return true; if (/^\s*\[earlier conversation compacted\]\s*$/i.test(s)) return true; return false; } function isRealUser(m) { if (!m || m.role !== 'user') return false; const c = String(m.content || ''); if (c.indexOf('') >= 0) return false; if (c.indexOf('[conversation summary]') >= 0) return false; if (c.indexOf('[memory]') === 0) return false; if (c.indexOf('[git status]') === 0) return false; return true; } // Keep native tool exchanges atomic: results must never outlive their calls. function messageGroups(messages) { const groups = []; for (const message of messages) { const previous = groups[groups.length - 1]; if (message.role === 'tool') { const calls = previous && previous[0].tool_calls; if (calls && calls.some((call) => call.id === message.tool_call_id)) previous.push(message); continue; } groups.push([message]); } return groups; } function rebuildHistory(messages, summary) { const list = Array.isArray(messages) ? messages : []; const systems = list.filter((m) => m.role === 'system'); const lastUser = lastRealUserIndex(list); // Older turns belong in the summary, never after the latest request. const tail = lastUser >= 0 ? list.slice(lastUser) : list.filter((m) => m.role !== 'system'); return systems.concat( { role: 'user', content: '[conversation summary]\n' + String(summary || '').trim() }, messageGroups(tail.filter((m) => m.role !== 'system')).flat() ); } function truncateMsg(m, maxChars) { if (!m) return m; const copy = Object.assign({}, m); const c = copy.content; if (typeof c === 'string' && c.length > maxChars) { copy.content = truncate.truncateWithMarker(c, maxChars); } else if (Array.isArray(c)) { copy.content = c.map((part) => { if (!part || typeof part !== 'object') return part; if (typeof part.text === 'string' && part.text.length > maxChars) { return Object.assign({}, part, { text: truncate.truncateWithMarker(part.text, maxChars) }); } return part; }); } return copy; } function lastRealUserIndex(list) { for (let i = list.length - 1; i >= 0; i--) { if (isRealUser(list[i])) return i; } return -1; } function overHistoryBudget(keep, budget) { return conversationTokens(keep) > budget; } function heuristicCompact(messages, opts) { opts = opts || {}; const budget = opts.budgetTokens || 6000; const list = messages || []; const tokens = conversationTokens(list); if (tokens <= budget || (!opts.aggressive && nonSystemCount(list) < MIN_COMPACT_MESSAGES && conversationTokens(list.filter((m) => m.role !== 'system')) <= 1024)) return list.slice(); const systems = list.filter((m) => m.role === 'system'); const lastUser = lastRealUserIndex(list); const request = lastUser >= 0 ? list[lastUser] : null; const older = list.slice(0, lastUser >= 0 ? lastUser : 0).filter((m) => m.role !== 'system'); const tail = list.slice(lastUser >= 0 ? lastUser + 1 : 0).filter((m) => m.role !== 'system'); let groups = messageGroups(tail); // Preserve an existing summary across repeated compactions. The fallback // carries real excerpts rather than replacing memory with a generic notice. const memory = transcript(older.concat(tail)); const fixed = systems.concat(request ? [request] : []); const spareChars = Math.max(0, (budget - conversationTokens(fixed) - 12) * CHAR_PER_TOKEN); const summaryCap = Math.min(2400, Math.floor(spareChars * (groups.length ? 0.4 : 1))); let summary = memory && summaryCap >= 64 ? { role: 'user', content: '[conversation summary]\n' + boundedExcerpt(memory, summaryCap) } : null; const assemble = () => systems.concat(summary ? [summary] : [], request ? [request] : [], groups.flat()); let keep = assemble(); // Shrink bulky results first; preserve call ids, arguments and ordering. for (const cap of [1600, 600, 180]) { if (!overHistoryBudget(keep, budget)) break; groups = groups.map((group) => group.map((m) => truncateMsg(m, cap))); keep = assemble(); } while (overHistoryBudget(keep, budget) && groups.length) { groups.shift(); keep = assemble(); } if (overHistoryBudget(keep, budget) && summary) { summary = null; keep = assemble(); } // The system instructions and latest request are never silently truncated. // If these alone exceed the window, the caller reports the overflow. return keep; } function boundedExcerpt(text, maxChars) { if (text.length <= maxChars) return text; const marker = '\n[earlier details omitted]\n'; const remaining = Math.max(0, maxChars - marker.length); const head = Math.floor(remaining * 0.6); return text.slice(0, head) + marker + text.slice(-(remaining - head)); } function compact(messages, opts) { return heuristicCompact(messages, opts); } function transcript(messages) { return (messages || []) .map((m) => { const role = m && m.role ? m.role : 'unknown'; const name = m && m.name ? ' ' + m.name : ''; const content = m && m.content != null ? m.content : ''; const body = typeof content === 'string' ? content : JSON.stringify(content); if (body.startsWith('[conversation summary]')) return body.slice('[conversation summary]'.length).trim(); return role + name + ':\n' + body + (m && m.tool_calls ? '\nTool calls: ' + JSON.stringify(m.tool_calls) : ''); }) .join('\n\n'); } function isVoice(opts) { return !!(opts && opts.voice); } function autoContinue(messages, opts) { if (isVoice(opts)) return null; const list = messages || []; const last = list[list.length - 1]; if (!last) return null; if (last.role === 'tool' || last.role === 'assistant') { return { role: 'user', content: '\nContinue the work from the summary. Do not wait for a new user request.\n', }; } return null; } function compactReminder(opts) { if (isVoice(opts)) { return ( '\n' + 'Context was compacted. Trust the summary and the last user request. Answer that request. Do not greet again.\n' + '' ); } return ( '\n' + 'Context was compacted. Trust the summary and the last user request. Re-read files before further edits. Follow AGENTS.md if present.\n' + '' ); } async function compactWithLlm(messages, opts) { opts = opts || {}; const fallback = () => heuristicCompact(messages, opts); if (!opts.aggressive && nonSystemCount(messages) < MIN_COMPACT_MESSAGES && conversationTokens((messages || []).filter((m) => m.role !== 'system')) <= 1024) { return (messages || []).slice(); } const complete = opts.complete; if (typeof complete !== 'function') return fallback(); const voice = isVoice(opts); const cap = opts.maxTranscriptChars || Math.max(1500, Math.min(24000, Math.floor((opts.budgetTokens || 4000) * CHAR_PER_TOKEN * 0.45))); const body = truncate.truncateWithMarker(transcript((messages || []).filter((m) => m.role !== 'system')), cap); const prompt = voice ? VOICE_COMPACT_PROMPT : COMPACT_PROMPT; const sys = voice ? 'Reply with the four summary sections only. No tools. Do not greet.' : 'Reply with the five summary sections only. No tools.'; try { const result = await complete({ history: [ { role: 'system', content: sys }, { role: 'user', content: prompt + '\n\n---\n\n' + body }, ], tools: [], }); const summary = result && result.text; if (isDegenerate(summary)) return fallback(); return heuristicCompact(rebuildHistory(messages, summary), Object.assign({}, opts, { aggressive: true })); } catch (_) { return fallback(); } } module.exports = { CHAR_PER_TOKEN, THRESHOLD, MIN_SUMMARY, MIN_COMPACT_MESSAGES, COMPACT_PROMPT, VOICE_COMPACT_PROMPT, conversationTokens, toolTokens, estimateTokens, historyBudget, shouldCompact, nonSystemCount, isOverflowError, usage, snapshot, isDegenerate, rebuildHistory, heuristicCompact, compact, autoContinue, compactReminder, compactWithLlm, };