@agenticmail/enterprise 0.5.327 → 0.5.329

package/src/runtime/compaction.ts

@@ -1,638 +0,0 @@
-/**
- * Advanced Context Compaction Engine
- * 
- * A multi-strategy, token-budget-aware compaction system that outperforms
- * naive summarization approaches. Key innovations:
- * 
- * 1. TIERED COMPRESSION — Three levels: trim tool results → extractive → LLM summary
- * 2. ATOMIC GROUPING — Tool use/result pairs never split
- * 3. TOKEN BUDGET — Calculates exact space to free, doesn't over-compact
- * 4. ROLLING SUMMARIES — Previous compaction summaries are preserved & chained
- * 5. IMPORTANCE SCORING — High-value messages kept verbatim (errors, decisions, IDs)
- * 6. PARALLEL CHUNK SUMMARIZATION — Large transcripts split and summarized concurrently
- * 7. STRUCTURED OUTPUT — Summary follows strict schema for reliable continuation
- */
-
-import type { AgentMessage, AgentConfig, RuntimeHooks } from './types.js';
-import { callLLM, estimateTokens, estimateMessageTokens } from './llm-client.js';
-
-// ─── Configuration ───────────────────────────────────────────────────────────
-
-/** Compact when context exceeds this fraction of the window */
-export const COMPACTION_THRESHOLD = 0.80;
-
-/** Target context usage after compaction (leave headroom for next turn) */
-const TARGET_USAGE = 0.45;
-
-/** Minimum messages to keep verbatim (recent conversation tail) */
-const MIN_KEEP_RECENT = 10;
-
-/** Maximum messages to keep verbatim */
-const MAX_KEEP_RECENT = 30;
-
-/** Max tokens for the LLM summary itself */
-const SUMMARY_MAX_TOKENS = 4096;
-
-/** Max transcript chars to send to LLM for summarization per chunk */
-const CHUNK_MAX_CHARS = 80_000;
-
-/** Max parallel summarization chunks */
-const MAX_PARALLEL_CHUNKS = 3;
-
-/** Tool result content longer than this gets trimmed in Tier 1 */
-const TOOL_RESULT_TRIM_THRESHOLD = 2000;
-
-/** Trimmed tool result max length */
-const TOOL_RESULT_TRIM_TO = 400;
-
-/** High-importance patterns — messages matching these are kept verbatim */
-const HIGH_IMPORTANCE_PATTERNS = [
-  /error|fail|exception|crash|bug/i,
-  /decision|decided|chose|choosing/i,
-  /important|critical|must|required/i,
-  /password|secret|key|token|credential/i,
-  /\b[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\b/, // UUIDs
-  /https?:\/\/\S{20,}/, // Long URLs
-  /\/[a-zA-Z][\w/.-]{10,}/, // File paths
-];
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-interface CompactionResult {
-  messages: AgentMessage[];
-  stats: CompactionStats;
-}
-
-interface CompactionStats {
-  strategy: 'none' | 'tier1_trim' | 'tier2_extractive' | 'tier3_llm';
-  messagesBefore: number;
-  messagesAfter: number;
-  tokensBefore: number;
-  tokensAfter: number;
-  msElapsed: number;
-  summaryTokens?: number;
-  llmInputTokens?: number;
-  llmOutputTokens?: number;
-  chunksUsed?: number;
-  previousSummariesChained?: number;
-}
-
-interface MessageGroup {
-  messages: AgentMessage[];
-  tokens: number;
-  importance: number;
-  isToolPair: boolean;
-  isPreviousSummary: boolean;
-}
-
-// ─── Main Entry Point ────────────────────────────────────────────────────────
-
-/**
- * Compact the message history to fit within the context window.
- * Uses a tiered approach — tries cheapest strategies first.
- */
-export async function compactContext(
-  messages: AgentMessage[],
-  config: AgentConfig,
-  hooks: RuntimeHooks,
-  options?: { apiKey?: string; sessionId?: string },
-): Promise<AgentMessage[]> {
-  const startMs = Date.now();
-  const contextWindowSize = config.contextWindowSize ?? 200_000;
-  const tokensBefore = estimateMessageTokens(messages);
-  const targetTokens = Math.floor(contextWindowSize * TARGET_USAGE);
-
-  // Don't compact if already under threshold
-  if (tokensBefore <= contextWindowSize * COMPACTION_THRESHOLD) {
-    return messages;
-  }
-
-  const tokensToFree = tokensBefore - targetTokens;
-  console.log(`[compaction] Need to free ~${tokensToFree} tokens (${tokensBefore} → target ${targetTokens})`);
-
-  // Split system messages from conversation
-  const systemMessages = messages.filter(m => m.role === 'system');
-  const nonSystem = messages.filter(m => m.role !== 'system');
-
-  if (nonSystem.length <= MIN_KEEP_RECENT) {
-    return messages; // Nothing to compact
-  }
-
-  // ─── Tier 1: Trim bloated tool results ─────────────────────────────────
-  const tier1Messages = trimToolResults(nonSystem);
-  const tier1Tokens = estimateMessageTokens([...systemMessages, ...tier1Messages]);
-
-  if (tier1Tokens <= contextWindowSize * COMPACTION_THRESHOLD) {
-    const stats: CompactionStats = {
-      strategy: 'tier1_trim',
-      messagesBefore: messages.length,
-      messagesAfter: systemMessages.length + tier1Messages.length,
-      tokensBefore,
-      tokensAfter: tier1Tokens,
-      msElapsed: Date.now() - startMs,
-    };
-    console.log(`[compaction] Tier 1 (trim tool results) sufficient: ${tokensBefore} → ${tier1Tokens} tokens in ${stats.msElapsed}ms`);
-    return [...systemMessages, ...tier1Messages];
-  }
-
-  // ─── Determine keep-recent boundary ────────────────────────────────────
-  const keepCount = calculateKeepRecent(tier1Messages, targetTokens, estimateMessageTokens(systemMessages));
-  const { toSummarize, keepRecent } = splitAtSafeBoundary(tier1Messages, keepCount);
-
-  if (toSummarize.length === 0) {
-    return messages; // Can't split safely
-  }
-
-  // ─── Group messages for importance scoring ─────────────────────────────
-  const groups = groupMessages(toSummarize);
-  const sortedGroups = groups.sort((a, b) => b.importance - a.importance);
-
-  // Separate previous compaction summaries (they chain)
-  const previousSummaries = sortedGroups.filter(g => g.isPreviousSummary);
-  const regularGroups = sortedGroups.filter(g => !g.isPreviousSummary);
-
-  // ─── Tier 2: Extractive (no LLM call) ─────────────────────────────────
-  const keepTokenBudget = estimateMessageTokens(systemMessages) + estimateMessageTokens(keepRecent);
-  const summaryBudget = targetTokens - keepTokenBudget;
-
-  if (!options?.apiKey || summaryBudget < 1000) {
-    // No API key or very little budget — use extractive
-    const summary = buildExtractiveSummary(previousSummaries, regularGroups, summaryBudget);
-    const result = assembleFinal(systemMessages, summary, keepRecent);
-    const stats: CompactionStats = {
-      strategy: 'tier2_extractive',
-      messagesBefore: messages.length,
-      messagesAfter: result.length,
-      tokensBefore,
-      tokensAfter: estimateMessageTokens(result),
-      msElapsed: Date.now() - startMs,
-      previousSummariesChained: previousSummaries.length,
-    };
-    console.log(`[compaction] Tier 2 (extractive): ${stats.tokensBefore} → ${stats.tokensAfter} tokens in ${stats.msElapsed}ms`);
-    await persistSummary(hooks, options?.sessionId, config.agentId, summary);
-    return result;
-  }
-
-  // ─── Tier 3: LLM-powered summarization ─────────────────────────────────
-  try {
-    const transcript = buildTranscript(previousSummaries, regularGroups);
-    const summary = await llmSummarize(transcript, config, options.apiKey, summaryBudget);
-    const result = assembleFinal(systemMessages, summary.text, keepRecent);
-    const tokensAfter = estimateMessageTokens(result);
-
-    const stats: CompactionStats = {
-      strategy: 'tier3_llm',
-      messagesBefore: messages.length,
-      messagesAfter: result.length,
-      tokensBefore,
-      tokensAfter,
-      msElapsed: Date.now() - startMs,
-      summaryTokens: estimateTokens(summary.text),
-      llmInputTokens: summary.inputTokens,
-      llmOutputTokens: summary.outputTokens,
-      chunksUsed: summary.chunks,
-      previousSummariesChained: previousSummaries.length,
-    };
-    console.log(`[compaction] Tier 3 (LLM): ${stats.tokensBefore} → ${stats.tokensAfter} tokens in ${stats.msElapsed}ms (${summary.chunks} chunks, ${summary.inputTokens}in/${summary.outputTokens}out)`);
-    await persistSummary(hooks, options?.sessionId, config.agentId, summary.text);
-    return result;
-  } catch (err: any) {
-    console.warn(`[compaction] LLM summarization failed: ${err.message} — falling back to extractive`);
-    const summary = buildExtractiveSummary(previousSummaries, regularGroups, summaryBudget);
-    const result = assembleFinal(systemMessages, summary, keepRecent);
-    await persistSummary(hooks, options?.sessionId, config.agentId, summary);
-    console.log(`[compaction] Extractive fallback: ${tokensBefore} → ${estimateMessageTokens(result)} tokens in ${Date.now() - startMs}ms`);
-    return result;
-  }
-}
-
-// ─── Tier 1: Trim Tool Results ───────────────────────────────────────────────
-
-function trimToolResults(messages: AgentMessage[]): AgentMessage[] {
-  return messages.map(msg => {
-    if (!Array.isArray(msg.content)) return msg;
-
-    let modified = false;
-    const newContent = (msg.content as any[]).map((block: any) => {
-      if (block.type === 'tool_result') {
-        const content = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
-        if (content.length > TOOL_RESULT_TRIM_THRESHOLD) {
-          modified = true;
-          return {
-            ...block,
-            content: content.slice(0, TOOL_RESULT_TRIM_TO) + `\n... [trimmed ${content.length - TOOL_RESULT_TRIM_TO} chars]`,
-          };
-        }
-      }
-      return block;
-    });
-
-    return modified ? { ...msg, content: newContent } : msg;
-  });
-}
-
-// ─── Keep-Recent Calculation ─────────────────────────────────────────────────
-
-function calculateKeepRecent(messages: AgentMessage[], targetTokens: number, systemTokens: number): number {
-  // Walk backwards from the end, accumulating tokens, until we hit the budget
-  // Reserve ~30% of target for the summary itself
-  const keepBudget = Math.floor((targetTokens - systemTokens) * 0.6);
-  let tokens = 0;
-  let count = 0;
-
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msgTokens = estimateMessageTokens([messages[i]]);
-    if (tokens + msgTokens > keepBudget && count >= MIN_KEEP_RECENT) break;
-    tokens += msgTokens;
-    count++;
-    if (count >= MAX_KEEP_RECENT) break;
-  }
-
-  return Math.max(MIN_KEEP_RECENT, count);
-}
-
-// ─── Safe Boundary Split ─────────────────────────────────────────────────────
-
-function splitAtSafeBoundary(messages: AgentMessage[], keepCount: number): {
-  toSummarize: AgentMessage[];
-  keepRecent: AgentMessage[];
-} {
-  let cutIndex = messages.length - keepCount;
-
-  // Walk backwards to avoid splitting tool_use/tool_result pairs
-  for (let i = cutIndex; i > 0; i--) {
-    const msg = messages[i];
-    if (msg.role === 'user' && Array.isArray(msg.content)) {
-      const hasToolResult = (msg.content as any[]).some((b: any) => b.type === 'tool_result');
-      if (hasToolResult) continue; // Don't cut here
-    }
-    cutIndex = i;
-    break;
-  }
-
-  return {
-    toSummarize: messages.slice(0, cutIndex),
-    keepRecent: messages.slice(cutIndex),
-  };
-}
-
-// ─── Message Grouping & Importance ───────────────────────────────────────────
-
-function groupMessages(messages: AgentMessage[]): MessageGroup[] {
-  const groups: MessageGroup[] = [];
-  let i = 0;
-
-  while (i < messages.length) {
-    const msg = messages[i];
-
-    // Check if this is a previous compaction summary
-    if (msg.role === 'user' && typeof msg.content === 'string' && msg.content.includes('[CONTEXT COMPACTION')) {
-      groups.push({
-        messages: [msg],
-        tokens: estimateMessageTokens([msg]),
-        importance: 10, // Highest — contains all prior context
-        isPreviousSummary: true,
-        isToolPair: false,
-      });
-      i++;
-      continue;
-    }
-
-    // Group tool_use (assistant) with following tool_result (user)
-    if (msg.role === 'assistant' && Array.isArray(msg.content) &&
-        (msg.content as any[]).some((b: any) => b.type === 'tool_use') &&
-        i + 1 < messages.length) {
-      const next = messages[i + 1];
-      if (next.role === 'user' && Array.isArray(next.content) &&
-          (next.content as any[]).some((b: any) => b.type === 'tool_result')) {
-        const pair = [msg, next];
-        groups.push({
-          messages: pair,
-          tokens: estimateMessageTokens(pair),
-          importance: scoreImportance(pair),
-          isToolPair: true,
-          isPreviousSummary: false,
-        });
-        i += 2;
-        continue;
-      }
-    }
-
-    // Single message
-    groups.push({
-      messages: [msg],
-      tokens: estimateMessageTokens([msg]),
-      importance: scoreImportance([msg]),
-      isToolPair: false,
-      isPreviousSummary: false,
-    });
-    i++;
-  }
-
-  return groups;
-}
-
-function scoreImportance(messages: AgentMessage[]): number {
-  let score = 1;
-  for (const msg of messages) {
-    const text = extractText(msg);
-
-    // User messages slightly more important (contain instructions)
-    if (msg.role === 'user') score += 1;
-
-    // Check high-importance patterns
-    for (const pattern of HIGH_IMPORTANCE_PATTERNS) {
-      if (pattern.test(text)) {
-        score += 2;
-        break; // One match is enough
-      }
-    }
-
-    // Error tool results are very important
-    if (Array.isArray(msg.content)) {
-      for (const block of msg.content as any[]) {
-        if (block.type === 'tool_result' && block.is_error) score += 3;
-      }
-    }
-
-    // Very short messages are less important (acks, "ok", etc.)
-    if (text.length < 20) score -= 1;
-
-    // Very long tool results are less important per-token (bulk data)
-    if (text.length > 5000) score -= 1;
-  }
-  return Math.max(0, score);
-}
-
-function extractText(msg: AgentMessage): string {
-  if (typeof msg.content === 'string') return msg.content;
-  if (Array.isArray(msg.content)) {
-    return (msg.content as any[]).map((b: any) => {
-      if (b.type === 'text') return b.text || '';
-      if (b.type === 'tool_use') return `${b.name}(${JSON.stringify(b.input || {}).slice(0, 200)})`;
-      if (b.type === 'tool_result') return String(b.content || '').slice(0, 500);
-      return '';
-    }).join(' ');
-  }
-  return '';
-}
-
-// ─── Extractive Summary (Tier 2) ────────────────────────────────────────────
-
-function buildExtractiveSummary(
-  previousSummaries: MessageGroup[],
-  groups: MessageGroup[],
-  tokenBudget: number,
-): string {
-  const parts: string[] = [];
-  let usedTokens = 0;
-
-  // Chain previous summaries first (they contain earlier context)
-  for (const sg of previousSummaries) {
-    const text = extractText(sg.messages[0]);
-    // Strip the "[CONTEXT COMPACTION...]" wrapper, keep the content
-    const content = text.replace(/^\[CONTEXT COMPACTION[^\]]*\]\s*/s, '');
-    const tokens = estimateTokens(content);
-    if (usedTokens + tokens < tokenBudget * 0.4) { // Use up to 40% for prior summaries
-      parts.push('## Prior Context (from earlier compaction)\n' + content);
-      usedTokens += tokens;
-    }
-  }
-
-  parts.push('\n## Recent Activity Summary');
-
-  // Add high-importance groups first, then fill with lower importance
-  // Already sorted by importance (descending)
-  for (const group of groups) {
-    if (usedTokens >= tokenBudget) break;
-
-    for (const msg of group.messages) {
-      const text = extractText(msg);
-      if (!text) continue;
-
-      // Truncate based on importance
-      const maxLen = group.importance >= 5 ? 800 : group.importance >= 3 ? 400 : 200;
-      const truncated = text.length > maxLen ? text.slice(0, maxLen) + '...' : text;
-      const line = `[${msg.role}]: ${truncated}`;
-      const lineTokens = estimateTokens(line);
-
-      if (usedTokens + lineTokens > tokenBudget) break;
-      parts.push(line);
-      usedTokens += lineTokens;
-    }
-  }
-
-  return parts.join('\n');
-}
-
-// ─── Transcript Builder ──────────────────────────────────────────────────────
-
-function buildTranscript(previousSummaries: MessageGroup[], groups: MessageGroup[]): string {
-  const parts: string[] = [];
-
-  // Include previous compaction summaries as context
-  for (const sg of previousSummaries) {
-    const text = extractText(sg.messages[0]);
-    const content = text.replace(/^\[CONTEXT COMPACTION[^\]]*\]\s*/s, '');
-    parts.push('=== PRIOR COMPACTION SUMMARY ===\n' + content.slice(0, 20_000) + '\n=== END PRIOR SUMMARY ===');
-  }
-
-  // Build transcript from groups (in original order — re-sort by position)
-  // Groups are sorted by importance, but transcript needs chronological order
-  const _chronoGroups = [...groups];
-  // We don't have explicit position, but original array order is chronological
-  // Since we only sorted a copy, use the original `groups` order... 
-  // Actually, groups come from groupMessages which is already chronological.
-  // They were sorted by importance for extractive, but for transcript we need chrono.
-  // We need to pass original order. Let's use regularGroups before sorting.
-  
-  for (const group of groups) {
-    for (const msg of group.messages) {
-      const text = extractText(msg);
-      if (text.length > 0) {
-        parts.push(`[${msg.role}]: ${text.slice(0, 1500)}`);
-      }
-    }
-  }
-
-  return parts.join('\n\n');
-}
-
-// ─── LLM Summarization (Tier 3) ─────────────────────────────────────────────
-
-const SUMMARY_SYSTEM_PROMPT = `You are a context compaction engine for an AI agent mid-task. Create a dense, lossless summary that the agent MUST be able to continue working from without any other context.
-
-RULES:
-- PRESERVE ALL: IDs, paths, URLs, emails, phone numbers, credentials (names only), version numbers, dates, amounts — use EXACT values
-- PRESERVE: Task goals, constraints, decisions made, errors encountered, workarounds found
-- PRESERVE: Current state — what was just done, what's next, any pending operations
-- COMPRESS: Routine tool calls (just note what tool was called and the outcome)
-- COMPRESS: Repeated similar operations (batch into counts: "read 12 files from /src/...")
-- OMIT: Pleasantries, acknowledgments, thinking-out-loud that didn't lead to decisions
-- FORMAT: Use ## headers for sections. Use bullet lists. Be dense but readable.
-- LENGTH: Use ALL available tokens. More detail = better continuation.
-
-Required sections:
-## Task & Goal
-## Completed Work (chronological)
-## Key Data (IDs, paths, URLs, names — EXACT values)
-## Decisions & Rationale
-## Current State
-## Next Steps
-## Errors & Lessons (if any)`;
-
-interface LLMSummaryResult {
-  text: string;
-  inputTokens: number;
-  outputTokens: number;
-  chunks: number;
-}
-
-async function llmSummarize(
-  transcript: string,
-  config: AgentConfig,
-  apiKey: string,
-  _tokenBudget: number,
-): Promise<LLMSummaryResult> {
-  // If transcript fits in one chunk, do single call
-  if (transcript.length <= CHUNK_MAX_CHARS) {
-    return singleChunkSummarize(transcript, config, apiKey);
-  }
-
-  // Split into chunks and summarize in parallel
-  const chunks = splitIntoChunks(transcript, CHUNK_MAX_CHARS);
-  const limitedChunks = chunks.slice(0, MAX_PARALLEL_CHUNKS);
-
-  console.log(`[compaction] Splitting transcript into ${limitedChunks.length} chunks for parallel summarization`);
-
-  const chunkResults = await Promise.all(
-    limitedChunks.map((chunk, idx) =>
-      singleChunkSummarize(
-        `[Chunk ${idx + 1}/${limitedChunks.length}]\n${chunk}`,
-        config,
-        apiKey,
-      ).catch(err => {
-        console.warn(`[compaction] Chunk ${idx + 1} failed: ${err.message}`);
-        return null;
-      })
-    )
-  );
-
-  // Merge chunk summaries
-  const validResults = chunkResults.filter((r): r is LLMSummaryResult => r !== null);
-
-  if (validResults.length === 0) {
-    throw new Error('All chunks failed');
-  }
-
-  if (validResults.length === 1) {
-    return { ...validResults[0], chunks: limitedChunks.length };
-  }
-
-  // Merge multiple chunk summaries into one
-  const mergedTranscript = validResults.map((r, i) => `=== Part ${i + 1} ===\n${r.text}`).join('\n\n');
-  const merged = await singleChunkSummarize(
-    `Merge these partial summaries into one cohesive summary:\n\n${mergedTranscript}`,
-    config,
-    apiKey,
-  );
-
-  return {
-    text: merged.text,
-    inputTokens: validResults.reduce((s, r) => s + r.inputTokens, 0) + merged.inputTokens,
-    outputTokens: validResults.reduce((s, r) => s + r.outputTokens, 0) + merged.outputTokens,
-    chunks: limitedChunks.length,
-  };
-}
-
-async function singleChunkSummarize(
-  transcript: string,
-  config: AgentConfig,
-  apiKey: string,
-): Promise<LLMSummaryResult> {
-  const response = await callLLM(
-    {
-      provider: config.model.provider,
-      modelId: config.model.modelId,
-      apiKey,
-    },
-    [
-      { role: 'system' as const, content: SUMMARY_SYSTEM_PROMPT },
-      { role: 'user' as const, content: `Summarize this conversation:\n\n${transcript}` },
-    ],
-    [],
-    { maxTokens: SUMMARY_MAX_TOKENS, temperature: 0.2 },
-  );
-
-  const text = response.textContent || '';
-  if (text.length < 50) throw new Error('Summary too short');
-
-  return {
-    text,
-    inputTokens: response.usage?.inputTokens || 0,
-    outputTokens: response.usage?.outputTokens || 0,
-    chunks: 1,
-  };
-}
-
-function splitIntoChunks(text: string, maxChars: number): string[] {
-  const chunks: string[] = [];
-  let start = 0;
-
-  while (start < text.length) {
-    let end = Math.min(start + maxChars, text.length);
-
-    // Try to split at a paragraph boundary
-    if (end < text.length) {
-      const lastParagraph = text.lastIndexOf('\n\n', end);
-      if (lastParagraph > start + maxChars * 0.5) {
-        end = lastParagraph + 2;
-      }
-    }
-
-    chunks.push(text.slice(start, end));
-    start = end;
-  }
-
-  return chunks;
-}
-
-// ─── Assembly ────────────────────────────────────────────────────────────────
-
-function assembleFinal(
-  systemMessages: AgentMessage[],
-  summaryText: string,
-  keepRecent: AgentMessage[],
-): AgentMessage[] {
-  const summaryMessage: AgentMessage = {
-    role: 'user' as const,
-    content: `[CONTEXT COMPACTION — Your earlier conversation was compressed to fit the context window. The summary below is authoritative — treat it as ground truth. Continue from where you left off.]\n\n${summaryText}`,
-  };
-
-  return [...systemMessages, summaryMessage, ...keepRecent];
-}
-
-// ─── Persistence ─────────────────────────────────────────────────────────────
-
-async function persistSummary(
-  hooks: RuntimeHooks,
-  sessionId: string | undefined,
-  agentId: string,
-  summaryText: string,
-): Promise<void> {
-  try {
-    await hooks.onContextCompaction(sessionId || '', agentId, summaryText);
-    console.log(`[compaction] Summary persisted to agent memory`);
-  } catch (err: any) {
-    console.warn(`[compaction] Memory save failed: ${err?.message}`);
-  }
-}
-
-// ─── Utilities ───────────────────────────────────────────────────────────────
-
-/**
- * Check if compaction is needed for the given messages + context window.
- */
-export function needsCompaction(messages: AgentMessage[], contextWindowSize: number): boolean {
-  return estimateMessageTokens(messages) > contextWindowSize * COMPACTION_THRESHOLD;
-}