Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { type PrePruneOptions, prePrune } from '../extensions/prePrune'
import { heuristicCount } from '../tokenizer/heuristic'
import { ChatMessage } from '../types'
/**
* Estimate token count for a message array.
*
* @deprecated since P.2 — prefer `LlmPort.getTokenCounter().countSync(...)` or
* the async `count(...)` variant. Kept exported as a thin alias over
* `heuristicCount` so existing call sites and tests continue to work while
* the codebase migrates.
*/
export function estimateTokens(messages: ChatMessage[]): number {
return heuristicCount(messages)
}
/**
* Split non-system messages into turns.
* Each "user" message starts a new turn (user + assistant + tool messages).
*/
export function splitTurns(nonSystemMsgs: ChatMessage[]): ChatMessage[][] {
const turns: ChatMessage[][] = []
let currentTurn: ChatMessage[] = []
for (const msg of nonSystemMsgs) {
if (msg.role === 'user' && currentTurn.length > 0) {
turns.push(currentTurn)
currentTurn = []
}
currentTurn.push(msg)
}
if (currentTurn.length > 0) {
turns.push(currentTurn)
}
return turns
}
// ─── T1.3 — Boundary alignment + last-user anchor ───────────────────────────
function isAssistantToolLead(msg: ChatMessage | undefined | null): boolean {
return (
!!msg && msg.role === 'assistant' && Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0
)
}
function isToolResult(msg: ChatMessage | undefined | null): boolean {
return !!msg && msg.role === 'tool' && typeof msg.tool_call_id === 'string'
}
/**
* Does any contiguous tool result in `messages[fromIdx..]` match one of the
* assistant.tool_calls ids at `leadIdx`? Walks forward while role === 'tool'.
*/
function hasMatchingToolAfter(messages: ChatMessage[], leadIdx: number, fromIdx: number): boolean {
const lead = messages[leadIdx]
if (!isAssistantToolLead(lead)) return false
const ids = new Set(lead.tool_calls!.map(tc => tc.id))
for (let j = fromIdx; j < messages.length; j++) {
const m = messages[j]
if (m.role !== 'tool') break
if (m.tool_call_id && ids.has(m.tool_call_id)) return true
}
return false
}
/**
* Does ANY tool result in the entire array match one of the assistant's
* tool_calls ids at `leadIdx`? Used for the pathological "orphan everywhere"
* forward-alignment check (Regla 2).
*/
function hasMatchingToolAnywhere(messages: ChatMessage[], leadIdx: number): boolean {
const lead = messages[leadIdx]
if (!isAssistantToolLead(lead)) return false
const ids = new Set(lead.tool_calls!.map(tc => tc.id))
for (let j = 0; j < messages.length; j++) {
if (j === leadIdx) continue
const m = messages[j]
if (m.role === 'tool' && m.tool_call_id && ids.has(m.tool_call_id)) return true
}
return false
}
/**
* Is `messages[idx]` a tool result whose lead assistant lives strictly before
* it? Walks back through contiguous tool messages to find the lead candidate.
*/
function isOrphanToolResult(messages: ChatMessage[], idx: number): boolean {
const here = messages[idx]
if (!isToolResult(here)) return false
let i = idx - 1
while (i >= 0 && messages[i].role === 'tool') {
i--
}
if (i < 0) return false
const leader = messages[i]
if (!isAssistantToolLead(leader)) return false
return leader.tool_calls!.some(tc => tc.id === here.tool_call_id)
}
/**
* Find the index of the last `user` message, or -1 if none.
*/
export function findLastUserIndex(messages: ChatMessage[]): number {
for (let i = messages.length - 1; i >= 0; i--) {
if (messages[i].role === 'user') return i
}
return -1
}
/**
* Translate a turn-array index into a message-array index. Returns the flat
* `nonSystemMsgs` index of the first message of `turns[turnIdx]`. For
* `turnIdx === turns.length` returns the total message count (i.e. "past the
* end" — useful when keepRecent is 0).
*/
export function turnIndexToMessageIndex(turns: ChatMessage[][], turnIdx: number): number {
const clamped = Math.max(0, Math.min(turnIdx, turns.length))
let sum = 0
for (let i = 0; i < clamped; i++) {
sum += turns[i].length
}
return sum
}
/**
* T1.3 — Align a proposed cut so it never splits an assistant.tool_calls /
* tool pair, and so the last user message always survives.
*
* `proposedCut` is the index in `messages` such that `messages[0..proposedCut-1]`
* is archived and `messages[proposedCut..]` is kept. Returns the aligned cut.
*
* Three rules applied in order:
* 1. Backward — walk back while the cut splits a tool-call pair (the
* message immediately before the cut is an assistant lead whose tool
* results live forward of the cut, OR the message at the cut is an
* orphan tool result whose lead lives before).
* 2. Forward — if after Rule 1 the cut still lands on an assistant lead
* with NO matching tool result anywhere, advance the cut past it
* (drops the orphan assistant from the kept set).
* 3. Last-user anchor — if the cut would archive the most recent user
* message, lower the cut to that user's index.
*
* Pure function. O(n). No allocations beyond per-check id sets.
*/
export function alignBoundary(messages: ChatMessage[], proposedCut: number): number {
let cut = Math.max(0, Math.min(proposedCut, messages.length))
// Rule 1 — backward alignment over tool-call pairs.
while (cut > 0) {
const left = messages[cut - 1]
const here = cut < messages.length ? messages[cut] : null
if (isAssistantToolLead(left) && hasMatchingToolAfter(messages, cut - 1, cut)) {
cut -= 1
continue
}
if (here && isOrphanToolResult(messages, cut)) {
cut -= 1
continue
}
break
}
// Rule 2 — forward alignment for completely-orphan assistant.tool_calls.
if (cut < messages.length) {
const here = messages[cut]
if (isAssistantToolLead(here) && !hasMatchingToolAnywhere(messages, cut)) {
cut += 1
}
}
// Rule 3 — last-user anchor.
const lastUserIdx = findLastUserIndex(messages)
if (lastUserIdx >= 0 && lastUserIdx < cut) {
cut = lastUserIdx
}
return cut
}
/**
* T1.4 — Compute the compaction effectiveness ratio `post/pre`.
*
* Returns `1.0` for the degenerate `pre === 0` case so callers always get a
* defined number. Re-used by `PressureContextManager.manage()` and exposed for
* tests; the manager uses `estimateTokens` (heuristic) — keep that path stable
* so the trigger threshold and the effectiveness measurement disagree at most
* by their shared rounding.
*/
export function measureCompactionRatio(pre: ChatMessage[], post: ChatMessage[]): number {
const preTokens = estimateTokens(pre)
if (preTokens <= 0) return 1.0
return estimateTokens(post) / preTokens
}
/**
* Apply an aligned cut to a split system/non-system pair. Convenience wrapper
* used by every compaction tier: feed it the system messages, the flat
* non-system messages, and the cut proposed by the tier policy. Returns the
* kept array (with system prepended) and the archived subarray.
*/
export function applyAlignedCut(
systemMsgs: ChatMessage[],
nonSystemMsgs: ChatMessage[],
proposedCut: number
): { kept: ChatMessage[]; archived: ChatMessage[] } {
const cut = alignBoundary(nonSystemMsgs, proposedCut)
const archived = nonSystemMsgs.slice(0, cut)
const tail = nonSystemMsgs.slice(cut)
return { kept: [...systemMsgs, ...tail], archived }
}
// ───────────────────────────────────────────────────────────────────────────
/**
* Compact conversation by keeping only the N most recent turns.
*
* Risk 5.5: Never compact the current turn's messages.
* The first message (system prompt) is always preserved.
*
* Strategy:
* 1. Always keep the system message (index 0)
* 2. Find user/assistant turn boundaries
* 3. Apply the T1.3 boundary aligner so cuts never split tool pairs and
* never archive the last user message.
*/
export async function compactConversation(
messages: ChatMessage[],
maxTurns: number = 5,
threshold: number = 80000,
measure: (msgs: ChatMessage[]) => Promise<number> = async msgs => heuristicCount(msgs),
prePruneOpts?: { enabled: boolean; options?: PrePruneOptions }
): Promise<ChatMessage[]> {
// #739: the caller (`runAgentLoop`) passes the measure behind
// `PressureContextManager`'s tier decision (`tierDecisionTokens`), so the
// threshold it scales from that manager's means the same history here.
// #731: under the threshold the history is returned untouched, by
// reference. `CLERUM_COMPACTION_PRE_PRUNE` defaults to `true`, so running
// pre-prune first would rewrite every history on every task, whatever the
// window. This mirrors `PressureContextManager.manage()`, which passes
// through below its threshold before pre-pruning.
if ((await measure(messages)) < threshold) {
return messages
}
// T1.2: pre-prune, then the turn cut only if pre-prune was not enough.
let working = messages
if (prePruneOpts?.enabled) {
working = prePrune(messages, prePruneOpts.options).messages
if ((await measure(working)) < threshold) {
return working
}
}
const systemMsgs = working.filter(m => m.role === 'system')
const nonSystemMsgs = working.filter(m => m.role !== 'system')
const turns = splitTurns(nonSystemMsgs)
if (turns.length <= maxTurns) return working
const proposedCut = turnIndexToMessageIndex(turns, turns.length - maxTurns)
const { kept } = applyAlignedCut(systemMsgs, nonSystemMsgs, proposedCut)
return kept
}