Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* T1.2 — Pre-pruning pass executed BEFORE invoking the LLM.
*
* Five deterministic, LLM-free passes that try to recover context tokens
* before the tiered compactor (MoveToWorkspace / Summarize / Truncate)
* pays an LLM call:
*
* 1. Collapse earlier `clerum__attachment_read` text pages into small
* identity+range stubs (pressure-gated by the caller).
* 2. Dedup tool outputs by canonical SHA-256 content hash.
* 3. One-line-summarize oversized tool outputs that live outside the
* protected tail.
* 4. JSON-safe truncate oversized `assistant.tool_calls[].arguments`.
* 5. Strip historical media (image content parts) from anything before
* the latest user message.
*
* Philosophy: local CPU is cheap compared to LLM tokens. Each pass is
* individually toggleable and a no-op if its condition doesn't apply. If the
* master flag is off, the function is NOT invoked; the existing tiers run
* bit-identical to pre-T1.2.
*
* Critical invariants:
* - **Linkages preserved**: pre-prune never inserts or deletes messages,
* never touches `tool_call_id` or `assistant.tool_calls[].id`. It only
* mutates `content` (string) and `arguments` (object). The caller runs
* `validateToolLinkages` as a post-step hard-fail safety net.
* - **Protected tail**: the last K turns (K = `protectedTailTurns`) stay
* complete. Pre-prune only operates on `[0, protectedTailStart)`.
* - **Pure**: the function returns a copy with mutated messages replaced
* by new copies; untouched entries keep referential identity. Caller
* decides when to assign.
*/
import { createHash } from 'node:crypto'
import { Counter } from 'prom-client'
import { extractInputPreview } from '../orchestration/toolUseLoop'
import { isLoopInjectedMessage } from '../orchestration/toolUseLoopMessages'
import { heuristicCount } from '../tokenizer/heuristic'
import type { ChatMessage, MessageContentPart, ToolCall } from '../types'
// T1.2 — Co-located Prometheus instrument (same pattern as `contextManager.ts`'s
// `clerumCompactionTotal` and `tokenizer/metrics.ts`). One counter is enough:
// the savings ratio can be derived from the running totals against the input
// token gauge from P.1 once it lands.
export const clerumPrePruneSavingsTokensTotal = new Counter({
name: 'clerum_pre_prune_savings_tokens_total',
help: 'Heuristic tokens reclaimed by T1.2 pre-pruning (sum of pre - post per call).',
})
/**
* Authoritative pressure snapshot supplied by the context manager. The
* attachment-page collapse only runs under real pressure; consumers that do
* not pass this object never collapse pages.
*/
export interface PrePrunePressure {
inputTokens: number
contextWindowTokens: number
}
export interface PrePruneOptions {
/** Cuántos turns proteger del tail (default 3). */
protectedTailTurns: number
/**
* Pass 2: tool messages whose `heuristicCount` exceeds this threshold are
* replaced by a one-line summary (default 200 tokens).
*
* The unit is `heuristicCount`'s `ceil(bytes / 4) + 4`, so the default
* collapses any tool result over 784 bytes of JSON-escaped content. For
* prose that is about where the earlier word count put it (151 words); for
* minified JSON it is far lower, because the word count read a result with
* no whitespace as a handful of words and never collapsed it. The lower
* point for JSON is intended: in the context managers pass 2 runs only
* once pressure has selected compaction, and it never touches the protected
* tail. The operator-enabled `token-trim` guardrail applies its own
* `maxInputTokens` gate instead, and with `maxInputTokens` unset it prunes
* every request.
*/
summaryThresholdTokens: number
/**
* Pass 3: `JSON.stringify(arguments)` se trunca cuando excede este budget
* (default 4096 bytes ≈ ~1024 tokens).
*/
maxArgsBytes: number
dedupEnabled: boolean
oneLineSummariesEnabled: boolean
jsonSafeTruncateEnabled: boolean
stripMediaEnabled: boolean
/**
* C17 — collapse earlier `clerum__attachment_read` text pages under
* pressure. Defaults to true; the pass still requires an explicit,
* finite-positive `pressure` argument to fire.
*/
attachmentPageCollapseEnabled?: boolean
}
export const DEFAULT_PRE_PRUNE_OPTIONS: PrePruneOptions = {
protectedTailTurns: 3,
summaryThresholdTokens: 200,
maxArgsBytes: 4096,
dedupEnabled: true,
oneLineSummariesEnabled: true,
jsonSafeTruncateEnabled: true,
stripMediaEnabled: true,
attachmentPageCollapseEnabled: true,
}
const DUPLICATE_PREFIX = '[duplicate of tool_call_id='
const ATTACHMENT_READ_TOOL_NAME = 'clerum__attachment_read'
// A later turn registers `clerum__attachment_read` only for the files attached
// to its own message, so the model must ask for the file again to re-read it.
const ATTACHMENT_PAGE_COLLAPSE_MARKER =
'[earlier attachment page collapsed; reattach the file in a new message to re-read it, and resume reading at nextOffset]'
const WRAPPED_ATTACHMENT_OUTPUT_PATTERN =
/^<tool_output name="clerum__attachment_read" sanitized="(true|false)">\n([\s\S]*)\n<\/tool_output>$/
export interface PrePruneResult {
messages: ChatMessage[]
preTokens: number
postTokens: number
passesApplied: string[]
}
/**
* Run the four-pass pre-prune over the message array. Returns the mutated
* copy plus pre/post token counts (heuristic) and a list of passes that
* actually fired. Caller (`PressureContextManager`) emits the observability
* event with this payload.
*/
export function prePrune(
messages: ChatMessage[],
opts: PrePruneOptions = DEFAULT_PRE_PRUNE_OPTIONS,
pressure?: PrePrunePressure
): PrePruneResult {
const preTokens = heuristicCount(messages)
const protectedTailStart = computeProtectedTailStart(messages, opts.protectedTailTurns)
const passesApplied: string[] = []
let out = messages
if (
opts.attachmentPageCollapseEnabled !== false &&
attachmentCollapsePressureQualifies(pressure)
) {
const next = collapseEarlierAttachmentPages(out)
if (next !== out) {
passesApplied.push('attachment_page_collapse')
out = next
}
}
if (opts.dedupEnabled) {
const next = dedupToolResults(out, protectedTailStart)
if (next !== out) {
passesApplied.push('dedup')
out = next
}
}
if (opts.oneLineSummariesEnabled) {
const next = oneLineSummaries(out, protectedTailStart, opts.summaryThresholdTokens)
if (next !== out) {
passesApplied.push('one_line_summaries')
out = next
}
}
if (opts.jsonSafeTruncateEnabled) {
const next = jsonSafeTruncateArgs(out, protectedTailStart, opts.maxArgsBytes)
if (next !== out) {
passesApplied.push('json_safe_truncate')
out = next
}
}
if (opts.stripMediaEnabled) {
const next = stripHistoricalMedia(out, protectedTailStart)
if (next !== out) {
passesApplied.push('strip_media')
out = next
}
}
const postTokens = heuristicCount(out)
return { messages: out, preTokens, postTokens, passesApplied }
}
function attachmentCollapsePressureQualifies(pressure: PrePrunePressure | undefined): boolean {
if (!pressure) return false
const { inputTokens, contextWindowTokens } = pressure
return (
Number.isFinite(inputTokens) &&
inputTokens >= 0 &&
Number.isFinite(contextWindowTokens) &&
contextWindowTokens > 0 &&
inputTokens >= 0.8 * contextWindowTokens
)
}
/**
* Compute the protected-tail start index. The last K user messages start
* the protected region; pre-prune leaves `messages[protectedTailStart..]`
* untouched. Returns `0` when there are fewer than K user messages — in
* that case the whole array is tail and no pass mutates anything.
*
* Mirrors the `splitTurns()` convention (each user message starts a turn).
* When T1.3's `alignBoundary` is invoked by the caller around the cut we
* compute here, the aligned cut is conservatively pushed earlier in cases
* where it would split a tool-call pair — that's safe, the protected
* region only grows.
*/
export function computeProtectedTailStart(messages: ChatMessage[], tailTurns: number): number {
if (tailTurns <= 0) return messages.length
let count = 0
for (let i = messages.length - 1; i >= 0; i--) {
if (messages[i].role === 'user') {
count++
if (count >= tailTurns) return i
}
}
return 0
}
// ─── Pass 0 — Collapse earlier attachment text pages ────────────────────────
/** The genuine native text-page result of `clerum__attachment_read`. */
interface AttachmentTextPage {
attachmentId: string
referenceId: string
kind: 'text'
byteRange: { offset: number; length: number }
truncated: boolean
limit?: 'max_bytes' | 'page_budget' | 'turn_budget'
nextOffset?: number
text: string
}
/**
* C17 — collapse the text of `clerum__attachment_read` pages that belong to
* turns strictly before the LATEST user message. The stub keeps every field
* the model needs to resume reading once the user attaches the file again —
* attachment/reference identity, byte range, truncation flag, `limit`,
* `nextOffset` and the tool linkage — and replaces only `text` with a fixed
* marker. Pages of the current turn (from the latest user message onwards)
* stay byte-identical, as do foreign tools, malformed payloads and binary
* results. User messages the loop injects itself (nudges, recovery prompts)
* do not start a turn, so they never move that boundary.
*
* Boundary note: this pass deliberately uses the latest-user boundary, not
* `computeProtectedTailStart`. A collapsed page cannot be re-read in a later
* turn: the tool is registered only for the files attached to that turn's
* message, so the marker tells the model to ask for the file again and to
* resume at `nextOffset`. The pinned digest (`referenceId`) lets a reattached
* copy be matched to the collapsed range. Under pressure these pages collapse
* even inside the protected tail, while every other pass keeps its
* protected-tail semantics unchanged.
*/
export function collapseEarlierAttachmentPages(messages: ChatMessage[]): ChatMessage[] {
const lastUserIndex = findLastUserIndex(messages)
if (lastUserIndex <= 0) return messages
let mutated: ChatMessage[] | null = null
for (let i = 0; i < lastUserIndex; i++) {
const msg = messages[i]
if (msg.role !== 'tool' || msg.name !== ATTACHMENT_READ_TOOL_NAME) continue
if (typeof msg.tool_call_id !== 'string' || msg.tool_call_id.length === 0) continue
const parsed = parseNativeAttachmentTextPage(msg.content)
if (!parsed) continue
if (parsed.page.text === ATTACHMENT_PAGE_COLLAPSE_MARKER) continue
if (mutated === null) mutated = messages.slice()
mutated[i] = { ...msg, content: buildAttachmentPageStub(parsed) }
}
return mutated ?? messages
}
function findLastUserIndex(messages: ChatMessage[]): number {
for (let i = messages.length - 1; i >= 0; i--) {
const message = messages[i]
if (
message.role === 'user' &&
message.imageOrigin !== 'tool_result' &&
!isLoopInjectedMessage(message)
) {
return i
}
}
return -1
}
function parseNativeAttachmentTextPage(
content: string
): { page: AttachmentTextPage; wrapperSanitized: boolean | null } | null {
let candidate = content
let wrapperSanitized: boolean | null = null
const wrapped = WRAPPED_ATTACHMENT_OUTPUT_PATTERN.exec(content)
if (wrapped) {
candidate = wrapped[2]!
wrapperSanitized = wrapped[1] === 'true'
}
let parsed: unknown
try {
parsed = JSON.parse(candidate)
} catch {
return null
}
if (!isAttachmentTextPage(parsed)) return null
return { page: parsed, wrapperSanitized }
}
function isAttachmentTextPage(value: unknown): value is AttachmentTextPage {
if (!value || typeof value !== 'object' || Array.isArray(value)) return false
const obj = value as Record<string, unknown>
const keys = Object.keys(obj)
if (keys.length < 6 || keys.length > 8) return false
const allowed = new Set([
'attachmentId',
'byteRange',
'kind',
'referenceId',
'text',
'truncated',
'limit',
'nextOffset',
])
if (keys.some(key => !allowed.has(key))) return false
for (const key of ['attachmentId', 'byteRange', 'kind', 'referenceId', 'text', 'truncated']) {
if (!(key in obj)) return false
}
if (typeof obj.attachmentId !== 'string' || obj.attachmentId.length === 0) return false
if (typeof obj.referenceId !== 'string' || obj.referenceId.length === 0) return false
if (obj.kind !== 'text') return false
if (typeof obj.text !== 'string') return false
if (typeof obj.truncated !== 'boolean') return false
const range = obj.byteRange
if (!range || typeof range !== 'object' || Array.isArray(range)) return false
const rangeKeys = Object.keys(range)
if (rangeKeys.length !== 2 || !('offset' in range) || !('length' in range)) return false
const offset = (range as Record<string, unknown>).offset
const length = (range as Record<string, unknown>).length
if (
typeof offset !== 'number' ||
!Number.isSafeInteger(offset) ||
offset < 0 ||
typeof length !== 'number' ||
!Number.isSafeInteger(length) ||
length < 0
) {
return false
}
if (!Number.isSafeInteger(offset + length)) return false
if (
'limit' in obj &&
!['max_bytes', 'page_budget', 'turn_budget'].includes(obj.limit as string)
) {
return false
}
if (
'nextOffset' in obj &&
(obj.truncated !== true ||
!Number.isSafeInteger(obj.nextOffset) ||
obj.nextOffset !== offset + length)
)
return false
return true
}
function buildAttachmentPageStub(parsed: {
page: AttachmentTextPage
wrapperSanitized: boolean | null
}): string {
const { page, wrapperSanitized } = parsed
const stub = JSON.stringify({
attachmentId: page.attachmentId,
referenceId: page.referenceId,
kind: 'text',
byteRange: { offset: page.byteRange.offset, length: page.byteRange.length },
truncated: page.truncated,
...(page.limit !== undefined ? { limit: page.limit } : {}),
...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
text: ATTACHMENT_PAGE_COLLAPSE_MARKER,
})
if (wrapperSanitized === null) return stub
// The attribute is rebuilt from the parsed flag, never copied from the input.
const sanitizedAttribute = wrapperSanitized ? 'true' : 'false'
return `<tool_output name="${ATTACHMENT_READ_TOOL_NAME}" sanitized="${sanitizedAttribute}">\n${stub}\n</tool_output>`
}
// ─── Pass 1 — Dedup tool outputs ────────────────────────────────────────────
/**
* Collapse `tool` messages with identical canonicalized content into
* back-references pointing at the first occurrence's `tool_call_id`. Only
* touches `messages[0..protectedTailStart)`; the tail is left intact so the
* LLM sees the most recent results in full.
*
* Canonicalization: JSON parsed-and-re-serialized with sorted keys for any
* object value, falling back to whitespace normalization for non-JSON
* content. Two semantically-identical payloads with different key orders
* (or extra whitespace) hash to the same value.
*/
export function dedupToolResults(
messages: ChatMessage[],
protectedTailStart: number
): ChatMessage[] {
if (protectedTailStart <= 0) return messages
const seen = new Map<string, { tool_call_id: string }>()
let mutated: ChatMessage[] | null = null
for (let i = 0; i < Math.min(protectedTailStart, messages.length); i++) {
const msg = messages[i]
if (msg.role !== 'tool') continue
if (!msg.tool_call_id) continue
if (msg.content.startsWith(DUPLICATE_PREFIX)) continue
const h = hash(msg.content)
const prior = seen.get(h)
if (prior) {
if (mutated === null) mutated = messages.slice()
mutated[i] = {
...msg,
content: `${DUPLICATE_PREFIX}${prior.tool_call_id}]`,
}
} else {
seen.set(h, { tool_call_id: msg.tool_call_id })
}
}
return mutated ?? messages
}
// ─── Pass 2 — One-line summaries ────────────────────────────────────────────
/**
* Replace `tool` messages outside the protected tail whose heuristic token
* count exceeds `threshold` with a one-line descriptor. Skips messages
* already collapsed by pass 1. Preserves `tool_call_id` (linkage invariant).
*
* Output format: `[<tool_name>] <args summary> -> <result summary>, <N> bytes`.
* If the agent later needs the full output, it will re-invoke the tool —
* which then trips pass 1 dedup against the live tail.
*/
export function oneLineSummaries(
messages: ChatMessage[],
protectedTailStart: number,
threshold: number
): ChatMessage[] {
if (protectedTailStart <= 0) return messages
let mutated: ChatMessage[] | null = null
for (let i = 0; i < Math.min(protectedTailStart, messages.length); i++) {
const msg = messages[i]
if (msg.role !== 'tool') continue
if (msg.content.startsWith(DUPLICATE_PREFIX)) continue
const tokens = heuristicCount([msg])
if (tokens <= threshold) continue
const byteCount = msg.content.length
const toolName = msg.name ?? 'unknown'
const argsSummary = inferArgsSummary(messages, msg.tool_call_id)
const resultSummary = inferResultSummary(msg.content)
const line = `[${toolName}] ${argsSummary} -> ${resultSummary}, ${byteCount} bytes`
if (mutated === null) mutated = messages.slice()
mutated[i] = { ...msg, content: line }
}
return mutated ?? messages
}
function inferArgsSummary(messages: ChatMessage[], toolCallId: string | undefined): string {
if (!toolCallId) return '(args unknown)'
for (let i = messages.length - 1; i >= 0; i--) {
const m = messages[i]
if (m.role !== 'assistant' || !m.tool_calls) continue
const tc = m.tool_calls.find(c => c.id === toolCallId)
if (!tc) continue
const preview = extractInputPreview(tc.name, tc.arguments)
if (preview) {
return preview.length > 80 ? preview.slice(0, 77) + '…' : preview
}
const serialized = safeStringifyArgs(tc.arguments)
return serialized.length > 80 ? `args=${serialized.slice(0, 77)}…` : `args=${serialized}`
}
return '(args unknown)'
}
function inferResultSummary(content: string): string {
const firstLine = content.split('\n')[0] ?? ''
return firstLine.length > 80 ? firstLine.slice(0, 77) + '…' : firstLine
}
function safeStringifyArgs(args: Record<string, unknown>): string {
try {
return JSON.stringify(args)
} catch {
return '(unserializable)'
}
}
// ─── Pass 3 — JSON-safe truncation of tool_calls arguments ──────────────────
/**
* Trim oversized `assistant.tool_calls[].arguments` while keeping the JSON
* parseable. The provider rejects with HTTP 400 on malformed args, so a
* naive `substring()` would crash the next call.
*
* Strategy: clone the args object, repeatedly find the longest string field
* (depth-first, including nested objects/arrays) and shrink it with a
* trailing `… (truncated, N chars omitted)` marker. Stop when the
* serialized payload fits the budget, when there are no more strings to
* cut, or after a small iteration cap (defence against pathological shapes).
*/
export function jsonSafeTruncateArgs(
messages: ChatMessage[],
protectedTailStart: number,
maxBytes: number
): ChatMessage[] {
if (protectedTailStart <= 0) return messages
let mutated: ChatMessage[] | null = null
for (let i = 0; i < Math.min(protectedTailStart, messages.length); i++) {
const msg = messages[i]
if (msg.role !== 'assistant' || !msg.tool_calls || msg.tool_calls.length === 0) continue
let toolCallsMutated: ToolCall[] | null = null
for (let j = 0; j < msg.tool_calls.length; j++) {
const tc = msg.tool_calls[j]
const serialized = safeStringifyArgs(tc.arguments)
if (serialized.length <= maxBytes) continue
const truncated = jsonSafeTruncate(tc.arguments, maxBytes)
if (toolCallsMutated === null) toolCallsMutated = msg.tool_calls.slice()
toolCallsMutated[j] = { ...tc, arguments: truncated }
}
if (toolCallsMutated !== null) {
if (mutated === null) mutated = messages.slice()
mutated[i] = { ...msg, tool_calls: toolCallsMutated }
}
}
return mutated ?? messages
}
function jsonSafeTruncate(
args: Record<string, unknown>,
maxBytes: number
): Record<string, unknown> {
const clone = structuredClone(args)
let serialized = JSON.stringify(clone)
let iterations = 0
const MAX_ITER = 50
while (serialized.length > maxBytes && iterations < MAX_ITER) {
const longest = findLongestStringField(clone)
if (!longest) break
const { ref, key, value } = longest
const overflow = serialized.length - maxBytes
// Leave room for the truncation marker (~40-50 chars) so the next
// serialization fits in the budget.
const newLen = Math.max(0, value.length - overflow - 50)
const replacement =
newLen < 10
? `… (truncated, ${value.length} chars omitted)`
: value.slice(0, newLen) + `… (truncated, ${value.length - newLen} chars omitted)`
// ref/key carry a union (object|array, string|number). Narrow once at
// assignment so TS accepts the indexed write either way.
;(ref as Record<string | number, unknown>)[key] = replacement
serialized = JSON.stringify(clone)
iterations++
}
return clone
}
interface LongestStringRef {
ref: Record<string, unknown> | unknown[]
key: string | number
value: string
}
function findLongestStringField(root: unknown): LongestStringRef | null {
let best: LongestStringRef | null = null
function walk(node: unknown): void {
if (!node || typeof node !== 'object') return
if (Array.isArray(node)) {
for (let i = 0; i < node.length; i++) {
const v = node[i]
if (typeof v === 'string') {
if (!best || v.length > best.value.length) {
best = { ref: node, key: i, value: v }
}
} else if (v && typeof v === 'object') {
walk(v)
}
}
return
}
const obj = node as Record<string, unknown>
for (const k of Object.keys(obj)) {
const v = obj[k]
if (typeof v === 'string') {
if (!best || v.length > best.value.length) {
best = { ref: obj, key: k, value: v }
}
} else if (v && typeof v === 'object') {
walk(v)
}
}
}
walk(root)
if (best === null) return null
// Sneak past the writable-key restriction: arrays support numeric writes.
return best as LongestStringRef
}
// ─── Pass 4 — Strip historical media ────────────────────────────────────────
/**
* Replace `image` content parts in every message strictly before the
* protected-tail region with `[image redacted — see turn N]` text parts.
* The protected tail (last K user messages and everything after) keeps its
* images intact — that's where the live frame for a vision call lives, and
* also where T1.3's `alignBoundary` guarantees pre-prune cannot strand a
* tool pair.
*
* Today (pre-B.7) mcp-host doesn't propagate `contentParts` between turns
* via `buildMessageHistory`, so this pass mostly fires inside long
* within-turn loops (e.g. repeated `desktop_screenshot`). Kept as a
* preventive guardrail for the B.7 future.
*
* Prior to the B3 fix this function used its own `findLastUserIndex` and
* stripped images from every message before the last user — bypassing the
* `protectedTailTurns` invariant that passes 1-3 already honor.
*/
export function stripHistoricalMedia(
messages: ChatMessage[],
protectedTailStart: number
): ChatMessage[] {
if (protectedTailStart <= 0) return messages
let mutated: ChatMessage[] | null = null
for (let i = 0; i < protectedTailStart; i++) {
const msg = messages[i]
if (!msg.contentParts || msg.contentParts.length === 0) continue
const hasImage = msg.contentParts.some(p => p.type === 'image')
if (!hasImage) continue
const newParts: MessageContentPart[] = msg.contentParts.map(part =>
part.type === 'image'
? {
type: 'text',
text: `[image redacted — see turn ${i}]`,
...(part.sourceIdentityOnly ? { sourceIdentityOnly: true as const } : {}),
}
: part
)
if (mutated === null) mutated = messages.slice()
mutated[i] = { ...msg, contentParts: newParts }
}
return mutated ?? messages
}
// ─── Canonicalization + hashing ─────────────────────────────────────────────
/**
* Normalize a `tool` message's `content` string before hashing. Two
* semantically-identical payloads (same JSON keys in different orders,
* varying whitespace) canonicalize to the same string so pass 1 collapses
* them. Non-JSON content gets whitespace-normalized only.
*
* Exported for tests; production callers go through `hash()`.
*/
export function canonicalize(content: string): string {
const trimmed = content.trim()
if (
(trimmed.startsWith('{') && trimmed.endsWith('}')) ||
(trimmed.startsWith('[') && trimmed.endsWith(']'))
) {
try {
const parsed = JSON.parse(trimmed)
return JSON.stringify(parsed, sortedReplacer)
} catch {
// fall through to whitespace normalization
}
}
return trimmed.replace(/\s+/g, ' ')
}
function sortedReplacer(_key: string, value: unknown): unknown {
if (value && typeof value === 'object' && !Array.isArray(value)) {
const obj = value as Record<string, unknown>
const sorted: Record<string, unknown> = {}
for (const k of Object.keys(obj).sort()) {
sorted[k] = obj[k]
}
return sorted
}
return value
}
export function hash(content: string): string {
return createHash('sha256').update(canonicalize(content)).digest('hex')
}