Something went wrong. Try again.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276/** * ThresholdCompactionTrigger — default `CompactionTrigger` (ARCH §5, §11, gy5n0k.3). * * `shouldCompact`: fires when `usage.context_tokens > contextWindow - reserveTokens` * (reserve = the headroom to keep free). Honors `enabled`; returns false when the * provider did not report `context_tokens` or the context window is unusable. The turn * loop consults this when a turn finishes, so the default (~20% reserve) compacts * between turns once the context passes ~80% of the window. * * `shouldCompactImmediately`: the emergency tier — fires when the context has reached * the window itself (100%). The turn loop consults it at iteration boundaries while the * agent is still running and compacts mid-turn; waiting for the turn to end would let * the next provider call overflow. * * `findCutPoint`: walks back from the newest entry accumulating a chars/4 token * estimate until the tail reaches `keepRecentTokens`, then snaps BACKWARDS to * the nearest user-message boundary. If the tail's turn is in-progress (an * unmatched `tool_call` with no `tool_result` yet), the cut is pushed back to the * previous user message so the in-progress turn stays with its predecessor. * When one recent agentic turn alone exceeds the budget, the cut may instead land * after a completed tool-call cycle within that turn; this avoids retaining tens * of thousands of tokens merely because there was no newer user boundary while * preserving valid tool-call/result pairs. When the whole window has only one user * message, the cut falls back to a completed cycle near the midpoint. * * Pure + unit-testable: takes entries + a token estimate; no SessionStore, no IO. * The caller (.7 AgentSession) computes the live window (entries after the last * compaction's `firstKeptEntryId`) and passes it here. */import type { CompactionTrigger, CompactionTriggerContext, CutOpts, CutPoint,} from '@/contracts/compaction-trigger';import type { Usage } from '@/types/usage';import type { SessionEntry, MessageEntry } from '@/types/session-entry';
/** Rough chars-per-token estimate (deterministic; no provider call). */const CHARS_PER_TOKEN = 4;
const isUserMessage = (e: SessionEntry): boolean => e.type === 'message' && e.details.message.role === 'user';
const isAssistantMessage = (e: SessionEntry): e is MessageEntry => e.type === 'message' && e.details.message.role === 'assistant';
/** Collect tool_call ids from an assistant message's content blocks. */const assistantToolCallIds = (e: MessageEntry): string[] => { const ids: string[] = []; for (const block of e.details.message.content) { if (block.type === 'tool_call') ids.push(block.id); } return ids;};
/** Rough chars/4 token estimate for a single entry. Deterministic; no provider. */export const estimateEntryTokens = (e: SessionEntry): number => { switch (e.type) { case 'message': { let chars = 0; for (const block of e.details.message.content) { switch (block.type) { case 'text': chars += block.text.length; break; case 'thinking': chars += block.text.length; break; case 'tool_call': chars += JSON.stringify(block.args).length; break; case 'tool_result': chars += JSON.stringify(block.content).length; break; } } return Math.ceil(chars / CHARS_PER_TOKEN); } case 'tool_result': return Math.ceil(JSON.stringify(e.details.content).length / CHARS_PER_TOKEN); case 'compaction': return Math.ceil(e.details.summary.length / CHARS_PER_TOKEN); case 'checkpoint': return Math.ceil(JSON.stringify(e.details.metadata ?? {}).length / CHARS_PER_TOKEN); }};
const sumTokens = (entries: SessionEntry[]): number => entries.reduce((acc, e) => acc + estimateEntryTokens(e), 0);
/** * Does the tail starting at `cutIdx` (a user message) contain an unmatched * `tool_call` (a turn in flight with no result yet)? Scans the turn that begins * at `cutIdx` up to the next user message or end of stream. */const hasUnmatchedToolCall = (entries: SessionEntry[], cutIdx: number): boolean => { const callIds = new Set<string>(); const resultIds = new Set<string>(); for (let i = cutIdx; i < entries.length; i++) { const e = entries[i]!; if (i > cutIdx && isUserMessage(e)) break; // next turn starts if (isAssistantMessage(e)) { for (const id of assistantToolCallIds(e)) callIds.add(id); } if (e.type === 'tool_result') resultIds.add(e.details.tool_call_id); } for (const id of callIds) { if (!resultIds.has(id)) return true; } return false;};
/** * Single-user long-chain fallback (ported from pi-vcc's `findMidCycleBoundary`, * reimplemented against shard's top-level `ToolResultEntry` model). Finds a * completed assistant→toolResult cycle (all of the assistant's tool_calls have * matching top-level `tool_result` entries) and returns the cut just after the * cycle nearest the midpoint of the window. */const completedCycleEnds = (entries: SessionEntry[], startIdx = 0): number[] => { const cycleEnds: number[] = []; let hasActiveCycle = false; const pendingCalls = new Set<string>(); for (let i = startIdx; i < entries.length; i++) { const entry = entries[i]!; if (isUserMessage(entry)) { hasActiveCycle = false; pendingCalls.clear(); } else if (isAssistantMessage(entry)) { pendingCalls.clear(); for (const id of assistantToolCallIds(entry)) pendingCalls.add(id); hasActiveCycle = pendingCalls.size > 0; } else if (entry.type === 'tool_result' && hasActiveCycle) { pendingCalls.delete(entry.details.tool_call_id); if (pendingCalls.size === 0) { cycleEnds.push(i); hasActiveCycle = false; } } } return cycleEnds;};
/** Earliest completed-cycle boundary whose non-empty tail fits the token budget. */const findBudgetedCycleCut = ( entries: SessionEntry[], startIdx: number, budgetTokens: number,): number | null => { if (budgetTokens <= 0) return null; const cycleEnds = completedCycleEnds(entries, startIdx); let tailTokens = 0; const tokensFrom = new Array<number>(entries.length + 1).fill(0); for (let i = entries.length - 1; i >= startIdx; i--) { tailTokens += estimateEntryTokens(entries[i]!); tokensFrom[i] = tailTokens; } for (const cycleEnd of cycleEnds) { const cutIdx = cycleEnd + 1; if (cutIdx < entries.length && tokensFrom[cutIdx]! <= budgetTokens) return cutIdx; } return null;};
const findCycleBoundaryCut = (entries: SessionEntry[]): CutPoint | null => { const n = entries.length; if (n <= 2) return null; const cycleEnds = completedCycleEnds(entries); if (cycleEnds.length === 0) return null; const target = Math.floor(n / 2); let best = cycleEnds[0]!; let bestDist = Math.abs(best - target); for (let i = 1; i < cycleEnds.length; i++) { const c = cycleEnds[i]!; const d = Math.abs(c - target); if (d < bestDist) { best = c; bestDist = d; } } const cutIdx = best + 1; // keep everything after the cycle if (cutIdx >= n) return null; return { firstKeptEntryId: entries[cutIdx]!.id, messagesToSummarize: entries.slice(0, cutIdx), tokensBefore: sumTokens(entries), };};
export class ThresholdCompactionTrigger implements CompactionTrigger { shouldCompact(usage: Usage, ctx: CompactionTriggerContext): boolean { if (!ctx.enabled) return false; if (usage.context_tokens === undefined) return false; if (ctx.contextWindow <= 0) return false; if (ctx.reserveTokens < 0) return false; return usage.context_tokens > ctx.contextWindow - ctx.reserveTokens; }
/** * The 100% emergency tier: fires when the reported context has reached the window * itself (`>= contextWindow`), regardless of the reserve — the NEXT provider call * would overflow, so compaction cannot wait for the turn to end. Same guards as * `shouldCompact` (disabled / unreported context / unusable window / invalid config * never fire); the reserve is deliberately not part of the comparison — a mis-set * reserve must not delay the emergency tier. */ shouldCompactImmediately(usage: Usage, ctx: CompactionTriggerContext): boolean { if (!ctx.enabled) return false; if (usage.context_tokens === undefined) return false; if (ctx.contextWindow <= 0) return false; if (ctx.reserveTokens < 0) return false; return usage.context_tokens >= ctx.contextWindow; }
findCutPoint(entries: SessionEntry[], opts: CutOpts): CutPoint | null { const n = entries.length; if (n <= 2) return null;
// 1. Walk back from the tail until the kept budget is met. let acc = 0; let target = 0; for (let i = n - 1; i >= 0; i--) { acc += estimateEntryTokens(entries[i]!); if (acc >= opts.keepRecentTokens) { target = i; break; } } if (target === 0) return null; // whole window fits the keep budget
// 2. Snap backwards to the nearest user-message boundary at or before target. let cutIdx = target; while (cutIdx > 0 && !isUserMessage(entries[cutIdx]!)) cutIdx--;
if (cutIdx === 0) { // Only one user message (or none in range): prefer a token-budgeted cycle // split, then fall back to the midpoint when no cycle leaves a small enough tail. const cycleCutIdx = findBudgetedCycleCut(entries, 0, opts.keepRecentTokens); if (cycleCutIdx !== null) { return { firstKeptEntryId: entries[cycleCutIdx]!.id, messagesToSummarize: entries.slice(0, cycleCutIdx), tokensBefore: sumTokens(entries), }; } return findCycleBoundaryCut(entries); }
// 3. Never split an unresolved turn: push back one user message so the // in-progress turn keeps its predecessor. if (hasUnmatchedToolCall(entries, cutIdx)) { let prev = cutIdx - 1; while (prev > 0 && !isUserMessage(entries[prev]!)) prev--; if (prev === 0) return findCycleBoundaryCut(entries); cutIdx = prev; }
// 4. A single agentic turn can dwarf the tail budget. A user-boundary-only // cut retained the entire 85k-token turn in practice. Split after the // earliest completed tool cycle that brings the remaining tail under // budget; complete call/result pairs remain together in the summary. // The kept history may therefore begin with a later assistant message. if (sumTokens(entries.slice(cutIdx)) > opts.keepRecentTokens) { const cycleCutIdx = findBudgetedCycleCut(entries, cutIdx, opts.keepRecentTokens); if (cycleCutIdx !== null) cutIdx = cycleCutIdx; }
return { firstKeptEntryId: entries[cutIdx]!.id, messagesToSummarize: entries.slice(0, cutIdx), tokensBefore: sumTokens(entries), }; }}