Files
waggle-os/packages/agent/src/long-task/messages-compressor.ts
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
moving
2026-09-02 10:10:29 +02:00

327 lines
14 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Messages-array compression — Phase 4.6 of agent-fix sprint
* (per decisions/2026-04-26-agent-fix-sprint-plan.md §4.6)
*
* Addresses the Phase 3 acceptance gate finding: ContextManager (Phase 3.3)
* compresses ONLY accumulated_context (audit log, ~450 tokens by step 30 —
* never crosses 4K threshold). Real LLM cost is dominated by the messages
* array (~16K tokens by step 30 on Opus). Phase 4.6 closes the gap by adding
* a SEPARATE compression layer for the messages array, invoked at the top of
* each retrieval-agent-loop iteration.
*
* REUSE / NON-DUPLICATION (per CLAUDE.md §3.6 check-before-create):
* - estimateStringTokens (per-string version) from context-compressor.ts
* for content-aware token estimation
* - pruneToolResults from context-compressor.ts (drops tool-result blobs in
* older messages to reduce size before LLM summarization)
* - COMPACTION_PROMPT from behavioral-spec.ts (proven summarizer prompt)
*
* NEW (this module):
* - summarizeMiddleViaLlmCall: drop-in replacement for context-compressor's
* fetch-based summarizeMiddle that uses Phase 2.1's LlmCallFn abstraction.
* - Simple message-count-based split (head + middle + tail) — PM brief
* specified `retainRecentTurns` as a COUNT, not the token-budget surface
* used by context-compressor.ts's splitProtectedRegions.
*
* NOT REFACTORED:
* - context-compressor.ts itself stays fetch-based for its existing
* consumers (harness + server). Future Sprint 12 cleanup could unify on
* LlmCallFn but that's separate scope.
*/
import {
estimateStringTokens,
pruneToolResults,
type CompressibleMessage,
} from '../context-compressor.js';
import { COMPACTION_PROMPT } from '../behavioral-spec.js';
import type { LlmCallFn } from '../retrieval-agent-loop.js';
// ─────────────────────────────────────────────────────────────────────────
// Public types
// ─────────────────────────────────────────────────────────────────────────
export interface MessagesCompressionEvent {
type: 'messages_compressed';
before_tokens: number;
after_tokens: number;
messages_before: number;
messages_after: number;
cost_usd: number;
summary_generated: boolean;
}
export interface MessagesContextManagerConfig {
/** Token budget for the messages array (per LLM call). */
budgetTokens: number;
/** Fraction of budget that triggers compression. Default 0.7. */
threshold?: number;
/**
* Number of recent TURNS to retain verbatim. One turn ≈ 2 messages
* (assistant + user, or vice-versa). Default 5 turns = 10 messages.
*/
retainRecentTurns?: number;
/**
* Number of head messages (after the system prompt) to keep verbatim.
* Default 1 (typically the kickoff user prompt — system is always retained).
*/
protectedHeadMessages?: number;
/**
* Per-string token estimator override. Default = estimateStringTokens
* (content-aware: prose 4.0 / code 3.2 / json 3.5 / mixed 2.5 chars-per-token).
* Caller can inject tiktoken or Anthropic count_tokens for exact counts.
*/
estimateTokensFn?: (text: string) => number;
/**
* LLM call function for summarizing the middle region. If absent, the
* middle is replaced with a structural placeholder ("[N compressed
* messages]") — pruning still happens but no semantic summary.
*/
llmCall?: LlmCallFn;
/** Model alias for the summarizer. Required if llmCall is provided. */
summarizationModel?: string;
/** max_tokens for the summarizer LLM call. Default 2000. */
summarizationMaxTokens?: number;
/** Optional callback for messages-compression events. */
onCompressionEvent?: (event: MessagesCompressionEvent) => void;
}
export interface CompressMessagesResult {
/** The (possibly compressed) messages array. */
messages: Array<{ role: string; content: string }>;
/** Updated running summary (carries forward across compressions). */
summary: string | null;
/** Whether compression actually fired this call. */
compressed: boolean;
}
// ─────────────────────────────────────────────────────────────────────────
// Constants
// ─────────────────────────────────────────────────────────────────────────
const DEFAULT_THRESHOLD = 0.7;
const DEFAULT_RETAIN_RECENT_TURNS = 5;
const DEFAULT_PROTECTED_HEAD_MESSAGES = 1;
const DEFAULT_SUMMARIZATION_MAX_TOKENS = 2000;
const PER_MESSAGE_ROLE_OVERHEAD_TOKENS = 4;
// ─────────────────────────────────────────────────────────────────────────
// Internal helpers
// ─────────────────────────────────────────────────────────────────────────
function estimateMessagesTokens(
messages: ReadonlyArray<{ role: string; content: string }>,
perStringFn: (text: string) => number,
): number {
let sum = 0;
for (const m of messages) {
sum += PER_MESSAGE_ROLE_OVERHEAD_TOKENS;
sum += perStringFn(m.content ?? '');
}
return sum;
}
interface SplitRegions {
head: Array<{ role: string; content: string }>;
middle: Array<{ role: string; content: string }>;
tail: Array<{ role: string; content: string }>;
}
/**
* Split messages into head (system + first N messages) / middle (compressible)
* / tail (last K turns × 2 messages, retained verbatim).
*
* One turn ≈ 2 messages, so retainRecentTurns × 2 messages are kept in tail.
* Head + tail must not overlap; if the conversation is short, middle may be empty.
*/
function splitForCompress(
messages: ReadonlyArray<{ role: string; content: string }>,
protectedHead: number,
retainRecentTurns: number,
): SplitRegions {
const headEnd = Math.min(1 + protectedHead, messages.length);
const tailStart = Math.max(headEnd, messages.length - retainRecentTurns * 2);
return {
head: messages.slice(0, headEnd).map(m => ({ ...m })),
middle: messages.slice(headEnd, tailStart).map(m => ({ ...m })),
tail: messages.slice(tailStart).map(m => ({ ...m })),
};
}
// ─────────────────────────────────────────────────────────────────────────
// LLM-call-based summarizer (replaces fetch-based summarizeMiddle)
// ─────────────────────────────────────────────────────────────────────────
interface SummarizeResult {
summary: string;
costUsd: number;
generated: boolean;
}
async function summarizeMiddleViaLlmCall(
middle: ReadonlyArray<CompressibleMessage>,
llmCall: LlmCallFn,
model: string,
maxTokens: number,
previousSummary: string | null,
): Promise<SummarizeResult> {
if (middle.length === 0) {
return { summary: previousSummary ?? '', costUsd: 0, generated: false };
}
const summarizerMessages: Array<{ role: string; content: string }> = [];
if (previousSummary) {
summarizerMessages.push({
role: 'system',
content: `You are summarizing a conversation that has been compressed before. Here is the previous summary:\n\n${previousSummary}\n\nNow incorporate the new messages below into an updated summary.`,
});
}
for (const msg of middle) {
summarizerMessages.push({
role: msg.role === 'system' ? 'user' : msg.role,
content: msg.content ?? '',
});
}
summarizerMessages.push({ role: 'user', content: COMPACTION_PROMPT });
const r = await llmCall({
model,
messages: summarizerMessages,
maxTokens,
temperature: 0.1,
// Compaction is a known-lightweight internal call → route to the cheap model
// (model-class-router). Saves Waggle-funded proxy spend on every compaction.
class: 'lightweight',
});
if (r.error || !r.content) {
return { summary: buildFallbackSummary(middle, previousSummary), costUsd: r.costUsd, generated: false };
}
return { summary: r.content, costUsd: r.costUsd, generated: true };
}
function buildFallbackSummary(
middle: ReadonlyArray<CompressibleMessage>,
previousSummary: string | null,
): string {
const lines: string[] = [];
if (previousSummary) lines.push('## Previous summary\n' + previousSummary);
lines.push(`## Compressed region (${middle.length} messages, no LLM summary)`);
const userFirstLines = middle
.filter(m => m.role === 'user')
.map(m => (m.content ?? '').split('\n')[0]?.slice(0, 100).trim())
.filter((l): l is string => Boolean(l && l.length > 8))
.slice(0, 5);
if (userFirstLines.length > 0) {
lines.push('Topics covered: ' + userFirstLines.join(' → '));
}
return lines.join('\n\n');
}
// ─────────────────────────────────────────────────────────────────────────
// Main entry point
// ─────────────────────────────────────────────────────────────────────────
/**
* Compress the messages array if it exceeds threshold. Returns the (possibly
* compressed) messages, a running summary (carries forward), and a boolean
* indicating whether compression actually fired.
*
* Pipeline (when triggered):
* 1. Prune tool-result-shaped blobs from older messages (no LLM, free).
* 2. Split into head (system + first N) / middle (compressible) / tail
* (last retainRecentTurns × 2 messages verbatim).
* 3. Summarize the middle via LLM (or fallback placeholder if no LLM).
* 4. Replace middle with single summary message; reassemble [head, summary, tail].
*
* Idempotency: if called twice in a row without growth, the second call is a
* no-op (under-threshold).
*/
export async function maybeCompressMessages(
messages: ReadonlyArray<{ role: string; content: string }>,
config: MessagesContextManagerConfig,
previousSummary: string | null,
): Promise<CompressMessagesResult> {
const stringEstimator = config.estimateTokensFn ?? estimateStringTokens;
const threshold = config.threshold ?? DEFAULT_THRESHOLD;
const protectedHead = config.protectedHeadMessages ?? DEFAULT_PROTECTED_HEAD_MESSAGES;
const retainRecentTurns = config.retainRecentTurns ?? DEFAULT_RETAIN_RECENT_TURNS;
const tokensBefore = estimateMessagesTokens(messages, stringEstimator);
if (tokensBefore <= config.budgetTokens * threshold) {
return { messages: messages.map(m => ({ ...m })), summary: previousSummary, compressed: false };
}
// Step 1: prune tool-result blobs (free, no LLM).
const pruneTailCount = retainRecentTurns * 2;
const pruned = pruneToolResults(messages, pruneTailCount);
// Step 2: split into head / middle / tail.
const regions = splitForCompress(pruned, protectedHead, retainRecentTurns);
// If middle is empty (very short conversation, head + tail covers everything),
// no compression is possible — return as-is (compressed=false).
if (regions.middle.length === 0) {
return { messages: pruned.map(m => ({ ...m })), summary: previousSummary, compressed: false };
}
// Step 3: summarize middle.
let summaryText: string;
let summaryGenerated = false;
let costUsd = 0;
if (config.llmCall && config.summarizationModel) {
const r = await summarizeMiddleViaLlmCall(
regions.middle,
config.llmCall,
config.summarizationModel,
config.summarizationMaxTokens ?? DEFAULT_SUMMARIZATION_MAX_TOKENS,
previousSummary,
);
summaryText = r.summary;
summaryGenerated = r.generated;
costUsd = r.costUsd;
} else {
summaryText = buildFallbackSummary(regions.middle, previousSummary);
}
// Step 4: replace middle with summary message.
const summaryMessage = {
role: 'system',
content: `[Compressed: ${regions.middle.length} earlier messages]\n${summaryText}`,
};
const newMessages = [...regions.head, summaryMessage, ...regions.tail];
const tokensAfter = estimateMessagesTokens(newMessages, stringEstimator);
if (config.onCompressionEvent) {
config.onCompressionEvent({
type: 'messages_compressed',
before_tokens: tokensBefore,
after_tokens: tokensAfter,
messages_before: messages.length,
messages_after: newMessages.length,
cost_usd: costUsd,
summary_generated: summaryGenerated,
});
}
return { messages: newMessages, summary: summaryText, compressed: true };
}
/**
* Returns true if the given messages array would trigger compression under
* the given config. Exposed for callers that want to check without invoking.
*/
export function shouldCompressMessages(
messages: ReadonlyArray<{ role: string; content: string }>,
config: MessagesContextManagerConfig,
): boolean {
const stringEstimator = config.estimateTokensFn ?? estimateStringTokens;
const threshold = config.threshold ?? DEFAULT_THRESHOLD;
return estimateMessagesTokens(messages, stringEstimator) > config.budgetTokens * threshold;
}