@animus-labs/cortex 0.2.0

package/src/compaction/compaction.ts

@@ -0,0 +1,386 @@
+/**
+ * Layer 2: Conversation Summarization.
+ *
+ * Replaces older conversation history with an LLM-generated summary
+ * while preserving a tail of recent turns. Uses the primary model
+ * for summarization quality (the conversation history is structurally
+ * complex with interleaved tool calls and multi-turn reasoning).
+ *
+ * Fires at 70% of context window (configurable). Emits lifecycle
+ * events (onBeforeCompaction, onPostCompaction) for consumer
+ * coordination (e.g., observational memory flush).
+ *
+ * References:
+ *   - compaction-strategy.md (Layer 2: Conversation Summarization)
+ *   - phase-5-compaction.md (5.3)
+ */
+
+import type { AgentMessage } from '../context-manager.js';
+import type { CompactionConfig, CompactionResult, CompactionTarget } from '../types.js';
+import { estimateTokens } from '../token-estimator.js';
+import { extractTextContent, isToolUseMessage, isToolResultMessage } from './microcompaction.js';
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+export const COMPACTION_DEFAULTS: CompactionConfig = {
+  threshold: 0.70,
+  preserveRecentTurns: 6,
+};
+
+// ---------------------------------------------------------------------------
+// Summarization prompt
+// ---------------------------------------------------------------------------
+
+const DEFAULT_SUMMARIZATION_PROMPT = `Your task is to create a detailed summary of the conversation so far. This summary will replace the conversation history, so it must capture everything needed to continue work without losing context. A small tail of the most recent turns is preserved separately and does not need to be repeated.
+
+Before writing your summary, analyze the conversation inside <analysis> tags. Walk through the conversation chronologically and note:
+- Each user request and how it was addressed
+- Key decisions and their rationale
+- Tool calls made, what they returned, and any errors
+- User feedback or corrections (especially when you were told to do something differently)
+- What was being worked on most recently
+
+The <analysis> block is a private scratchpad. Keep it concise (a line or two per point). Save all detail for the <summary> block.
+
+Then write your summary inside <summary> tags with the following sections:
+
+1. Primary Request and Intent
+   Capture all user requests and intents in detail. Preserve the user's exact words for directives, preferences, and constraints.
+
+2. Key Technical Concepts
+   List all important technical concepts, technologies, and frameworks discussed.
+
+3. Files and Code Sections
+   Enumerate specific files and code sections examined, modified, or created. Include file paths and relevant code snippets. For each file, summarize why it was read or edited and what changed.
+
+4. Tool Call Outcomes
+   What tools were called, what they found, and what failed. Include specific file paths, function names, URLs, error messages, and return values. Pay special attention to tool results that informed later decisions.
+
+5. Errors and Fixes
+   List all errors encountered and how they were resolved. Include specific user feedback received, especially corrections or redirections.
+
+6. All User Messages
+   List ALL user messages that are not tool results. These are critical for understanding the user's feedback and changing intent. Preserve the user's exact words.
+
+7. Problem Solving
+   Document problems solved and any ongoing troubleshooting efforts.
+
+8. Pending Tasks
+   Outline any pending tasks that have been explicitly requested but not yet completed.
+
+9. Current Work
+   Describe precisely what was being worked on immediately before this summary. Include file names, code snippets, and the specific state of the work. This section is the most important for seamless continuation.
+
+10. Key Decisions (Cumulative)
+    If a previous compaction summary exists in the conversation, carry forward its Key Decisions section and append any new decisions from this cycle. This section grows across compactions to prevent progressive loss of important decisions.
+
+11. Optional Next Step
+    List the next step related to the most recent work, but ONLY if it is directly in line with the user's most recent explicit request. If the last task was concluded, do not suggest tangential work. Include direct quotes from the conversation showing exactly what task was in progress.
+
+When preserving details, extract and retain exact values rather than paraphrasing:
+- File paths, directory names, and line numbers
+- URLs, API endpoints, and query parameters
+- Function names, class names, variable names
+- IDs, hashes, version numbers, and configuration values
+- Error messages and status codes
+- Specific quantities, dates, and thresholds
+
+Be thorough. Err on the side of including information that would prevent duplicate work or repeated mistakes.`;
+
+// ---------------------------------------------------------------------------
+// Summary extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the <summary> content from the LLM's compaction output.
+ * The prompt asks for <analysis> (scratchpad) then <summary> (the actual summary).
+ * We strip the analysis and keep only the summary content.
+ * If no <summary> tags are found, return the full output (the model may
+ * have skipped the tags but still produced useful content).
+ */
+export function extractSummaryContent(raw: string): string {
+  const match = raw.match(/<summary>([\s\S]*?)<\/summary>/);
+  if (match?.[1]) {
+    return match[1].trim();
+  }
+  // Fallback: strip <analysis> block if present, return the rest
+  const stripped = raw.replace(/<analysis>[\s\S]*?<\/analysis>/g, '').trim();
+  return stripped || raw.trim();
+}
+
+// ---------------------------------------------------------------------------
+// Summarization
+// ---------------------------------------------------------------------------
+
+/**
+ * Partition conversation history into compaction target and preserved tail.
+ *
+ * @param history - The full conversation history (post-slot region)
+ * @param preserveRecentTurns - Number of recent turns to preserve
+ * @returns [target, preserved] where target is summarized and preserved is kept verbatim
+ */
+export function partitionHistory(
+  history: AgentMessage[],
+  preserveRecentTurns: number,
+): [AgentMessage[], AgentMessage[]] {
+  if (history.length <= preserveRecentTurns) {
+    return [[], history];
+  }
+
+  let splitPoint = history.length - preserveRecentTurns;
+
+  // Never split between a tool_use (assistant) and its tool_result (user).
+  // If the split lands on a tool_result whose preceding message is a tool_use,
+  // move the split back one so the entire pair goes into the preserved tail.
+  if (
+    splitPoint > 0 &&
+    splitPoint < history.length &&
+    isToolResultMessage(history[splitPoint]!) &&
+    isToolUseMessage(history[splitPoint - 1]!)
+  ) {
+    splitPoint -= 1;
+  }
+
+  // Guard: don't create an empty target from the adjustment
+  if (splitPoint <= 0) {
+    return [[], history];
+  }
+
+  return [history.slice(0, splitPoint), history.slice(splitPoint)];
+}
+
+/**
+ * Build the compaction summary message wrapping it in XML tags.
+ *
+ * @param summary - The LLM-generated summary text
+ * @param turnsCompacted - Number of turns that were summarized
+ * @returns A user-role message containing the tagged summary
+ */
+export function buildSummaryMessage(
+  summary: string,
+  turnsCompacted: number,
+): AgentMessage {
+  const timestamp = new Date().toISOString();
+  const content = `<compaction-summary generated="${timestamp}" turns-summarized="${turnsCompacted}">\n${summary}\n</compaction-summary>`;
+  return { role: 'user', content, timestamp: Date.now() };
+}
+
+/**
+ * Format conversation turns for the summarization prompt.
+ * Extracts text content and labels each turn with role.
+ */
+export function formatTurnsForSummarization(turns: AgentMessage[]): string {
+  // No per-turn truncation. The compaction target is already bounded by
+  // partitionHistory (everything minus the preserved tail), and the
+  // summarizer needs access to full turn content for high-quality
+  // compression. See compaction-strategy.md Layer 2.
+  return turns
+    .map((msg, i) => {
+      const text = extractTextContent(msg);
+      return `[Turn ${i + 1}] ${msg.role}:\n${text}`;
+    })
+    .join('\n\n---\n\n');
+}
+
+/**
+ * Type for the LLM completion function.
+ * Matches the signature of CortexAgent.directComplete().
+ */
+export type CompleteFn = (context: {
+  systemPrompt: string;
+  messages: unknown[];
+}) => Promise<string>;
+
+/**
+ * Type for the consumer's onBeforeCompaction handler.
+ */
+export type BeforeCompactionHandler = (target: CompactionTarget) => Promise<void>;
+
+/**
+ * Type for the consumer's onPostCompaction handler.
+ */
+export type PostCompactionHandler = (result: CompactionResult) => void;
+
+/**
+ * Type for the consumer's onCompactionError handler.
+ */
+export type CompactionErrorHandler = (error: Error) => void;
+
+/**
+ * Run Layer 2 conversation summarization.
+ *
+ * Steps:
+ * 1. Partition history into target and preserved tail
+ * 2. Emit onBeforeCompaction (awaited)
+ * 3. Generate summary via LLM
+ * 4. Build new history: [summary message] + [preserved tail]
+ * 5. Emit onPostCompaction
+ *
+ * @param history - Current conversation history (post-slot region)
+ * @param config - Compaction configuration
+ * @param complete - LLM completion function
+ * @param handlers - Consumer lifecycle handlers
+ * @returns The new conversation history and compaction result
+ */
+export async function runCompaction(
+  history: AgentMessage[],
+  config: CompactionConfig,
+  complete: CompleteFn,
+  handlers: {
+    onBeforeCompaction?: BeforeCompactionHandler[];
+    onPostCompaction?: PostCompactionHandler[];
+    onCompactionError?: CompactionErrorHandler[];
+  } = {},
+  /** Actual full-context token count (includes system prompt, slots, tools). When provided, used as tokensBefore instead of text-only heuristic. */
+  actualContextTokens?: number,
+): Promise<{ newHistory: AgentMessage[]; result: CompactionResult }> {
+  const [target, preserved] = partitionHistory(history, config.preserveRecentTurns);
+
+  if (target.length === 0) {
+    // Nothing to compact; not enough history
+    throw new Error('Not enough conversation history to compact');
+  }
+
+  // Compute text-only heuristic for history content.
+  const historyTextTokens = estimateTokens(
+    history.map(m => extractTextContent(m)).join('\n'),
+  );
+
+  // Use actual full-context token count when provided (includes system prompt,
+  // slots, tool definitions); fall back to text-only heuristic for backward compat.
+  const tokensBefore = actualContextTokens ?? historyTextTokens;
+
+  // Overhead = system prompt + slots + tool definitions (everything except history text).
+  // Used to compute tokensAfter on the same basis as tokensBefore.
+  const overhead = actualContextTokens ? Math.max(0, actualContextTokens - historyTextTokens) : 0;
+
+  // Build compaction target info for the event
+  const targetInfo: CompactionTarget = {
+    turnsToCompact: target.length,
+    estimatedTokens: estimateTokens(
+      target.map(m => extractTextContent(m)).join('\n'),
+    ),
+  };
+
+  // Emit onBeforeCompaction (awaited)
+  if (handlers.onBeforeCompaction) {
+    for (const handler of handlers.onBeforeCompaction) {
+      await handler(targetInfo);
+    }
+  }
+
+  // Generate summary via LLM
+  const prompt = config.customPrompt ?? DEFAULT_SUMMARIZATION_PROMPT;
+  const turnsText = formatTurnsForSummarization(target);
+
+  let summary: string;
+  try {
+    summary = await complete({
+      systemPrompt: prompt,
+      messages: [
+        {
+          role: 'user',
+          content: `Here are the conversation turns to summarize:\n\n${turnsText}`,
+        },
+      ],
+    });
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    // Emit compaction error
+    if (handlers.onCompactionError) {
+      for (const handler of handlers.onCompactionError) {
+        try {
+          handler(error);
+        } catch {
+          // Swallow handler errors
+        }
+      }
+    }
+    throw error;
+  }
+
+  // Extract summary content from <summary> tags, stripping <analysis>
+  const parsedSummary = extractSummaryContent(summary);
+
+  // Build new history
+  const summaryMessage = buildSummaryMessage(parsedSummary, target.length);
+  const newHistory = [summaryMessage, ...preserved];
+
+  // Calculate result metrics. Include the same overhead (system prompt, slots,
+  // tool definitions) so tokensBefore and tokensAfter are on the same basis.
+  const newHistoryTextTokens = estimateTokens(
+    newHistory.map(m => extractTextContent(m)).join('\n'),
+  );
+  const tokensAfter = overhead + newHistoryTextTokens;
+  const summaryTokens = estimateTokens(parsedSummary);
+
+  // The oldest preserved turn's index in the original history.
+  // target.length is the split point: all turns before it were compacted.
+  const oldestPreservedIndex = target.length;
+
+  // Attempt to find a timestamp in the preserved messages; null if not found.
+  const oldestPreservedTimestamp = findOldestTimestamp(preserved);
+
+  const result: CompactionResult = {
+    tokensBefore,
+    tokensAfter,
+    turnsCompacted: target.length,
+    turnsPreserved: preserved.length,
+    summaryTokens,
+    oldestPreservedTimestamp,
+    oldestPreservedIndex,
+    summary: parsedSummary,
+  };
+
+  // Emit onPostCompaction
+  if (handlers.onPostCompaction) {
+    for (const handler of handlers.onPostCompaction) {
+      try {
+        handler(result);
+      } catch {
+        // Swallow handler errors
+      }
+    }
+  }
+
+  return { newHistory, result };
+}
+
+/**
+ * Attempt to find the oldest timestamp in a set of messages.
+ *
+ * Scans message content for ISO date patterns. Returns the first match
+ * or null if none found. This is a best-effort heuristic; the consumer
+ * should prefer `oldestPreservedIndex` from CompactionResult for
+ * reliable timestamp resolution via their own database.
+ */
+function findOldestTimestamp(messages: AgentMessage[]): string | null {
+  const isoPattern = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+
+  for (const msg of messages) {
+    const text = extractTextContent(msg);
+    const match = isoPattern.exec(text);
+    if (match) {
+      return match[0];
+    }
+  }
+
+  // No ISO timestamp found in preserved messages. Return null rather
+  // than Date.now() so the consumer knows no timestamp was found and
+  // can fall back to oldestPreservedIndex for database-level resolution.
+  return null;
+}
+
+/**
+ * Check if compaction should trigger based on token count and threshold.
+ */
+export function shouldCompact(
+  currentTokens: number,
+  contextWindow: number,
+  threshold: number,
+): boolean {
+  if (contextWindow <= 0) return false;
+  return (currentTokens / contextWindow) >= threshold;
+}

package/src/compaction/failsafe.ts

@@ -0,0 +1,185 @@
+/**
+ * Layer 3: Emergency Truncation (Failsafe).
+ *
+ * Last-resort truncation when Layer 2 fails or context is still too large.
+ * Drops the oldest conversation turns purely mechanically (no LLM call).
+ * Preserves structural integrity: tool_use/tool_result pairs are dropped together.
+ *
+ * Triggers at 90% of context window (configurable), or reactively when
+ * the API returns a context overflow error.
+ *
+ * This layer also serves as a mid-loop safety valve: it fires inside
+ * transformContext during the agentic loop when estimated token count
+ * exceeds 90%. Mid-loop truncation does NOT emit onBeforeCompaction
+ * (no observational memory processing mid-loop).
+ *
+ * References:
+ *   - compaction-strategy.md (Layer 3: Emergency Truncation)
+ *   - phase-5-compaction.md (5.4)
+ */
+
+import type { AgentMessage } from '../context-manager.js';
+import type { FailsafeConfig } from '../types.js';
+import { estimateTokens } from '../token-estimator.js';
+import { isToolResultMessage, isToolUseMessage, extractTextContent } from './microcompaction.js';
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+export const FAILSAFE_DEFAULTS: FailsafeConfig = {
+  threshold: 0.90,
+};
+
+/**
+ * Minimum number of recent turns to preserve during emergency truncation.
+ * Fewer turns preserved than Layer 2 since this is a last resort.
+ */
+const FAILSAFE_PRESERVE_TURNS = 3;
+
+// ---------------------------------------------------------------------------
+// Truncation
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of an emergency truncation operation.
+ */
+export interface FailsafeTruncationResult {
+  /** The truncated conversation history. */
+  newHistory: AgentMessage[];
+  /** Number of turns removed. */
+  turnsRemoved: number;
+  /** Estimated tokens after truncation. */
+  tokensAfter: number;
+}
+
+/**
+ * Find structural pairs in conversation history.
+ * A tool_use message and its corresponding tool_result form a pair.
+ * When dropping one, we must drop both.
+ *
+ * Returns indices that should be dropped together for each index.
+ * If a message at index i is part of a pair, pairMap[i] contains
+ * all indices in that pair.
+ */
+function findStructuralPairs(history: AgentMessage[]): Map<number, number[]> {
+  const pairMap = new Map<number, number[]>();
+
+  for (let i = 0; i < history.length; i++) {
+    const msg = history[i]!;
+
+    if (isToolUseMessage(msg)) {
+      // Look for the corresponding tool_result in the next message
+      if (i + 1 < history.length && isToolResultMessage(history[i + 1]!)) {
+        const pair = [i, i + 1];
+        pairMap.set(i, pair);
+        pairMap.set(i + 1, pair);
+      }
+    }
+  }
+
+  return pairMap;
+}
+
+/**
+ * Perform emergency truncation on conversation history.
+ *
+ * Drops the oldest turns (preserving structural pairs) until the
+ * estimated token count drops below the threshold, or until only
+ * the preserved tail remains.
+ *
+ * @param history - Conversation history (post-slot region)
+ * @param contextWindow - Total context window size in tokens
+ * @param slotTokens - Estimated tokens used by slots
+ * @param threshold - Usage ratio threshold (default 0.90)
+ * @returns Truncation result with new history and metrics
+ */
+export function emergencyTruncate(
+  history: AgentMessage[],
+  contextWindow: number,
+  slotTokens: number,
+  threshold: number = FAILSAFE_DEFAULTS.threshold,
+): FailsafeTruncationResult {
+  if (history.length === 0) {
+    return { newHistory: [], turnsRemoved: 0, tokensAfter: slotTokens };
+  }
+
+  const targetTokens = contextWindow * threshold;
+  const pairMap = findStructuralPairs(history);
+  const dropped = new Set<number>();
+
+  // Calculate initial token estimate
+  let currentTokens = slotTokens + estimateTokens(
+    history.map(m => extractTextContent(m)).join('\n'),
+  );
+
+  // Drop from the front, but respect the preserved tail
+  const preserveFrom = Math.max(0, history.length - FAILSAFE_PRESERVE_TURNS);
+  let i = 0;
+
+  while (currentTokens > targetTokens && i < preserveFrom) {
+    if (dropped.has(i)) {
+      i++;
+      continue;
+    }
+
+    // Get all indices that must be dropped together
+    const pair = pairMap.get(i);
+    const indicesToDrop = pair ?? [i];
+
+    // Check that none of the pair indices are in the preserved tail
+    const canDrop = indicesToDrop.every(idx => idx < preserveFrom);
+    if (!canDrop) {
+      i++;
+      continue;
+    }
+
+    // Drop the turn(s)
+    for (const idx of indicesToDrop) {
+      const msgTokens = estimateTokens(extractTextContent(history[idx]!));
+      currentTokens -= msgTokens;
+      dropped.add(idx);
+    }
+
+    i++;
+  }
+
+  // Build new history excluding dropped messages
+  const newHistory = history.filter((_, idx) => !dropped.has(idx));
+
+  return {
+    newHistory,
+    turnsRemoved: dropped.size,
+    tokensAfter: currentTokens,
+  };
+}
+
+/**
+ * Check if emergency truncation should fire based on token count.
+ */
+export function shouldTruncate(
+  currentTokens: number,
+  contextWindow: number,
+  threshold: number = FAILSAFE_DEFAULTS.threshold,
+): boolean {
+  if (contextWindow <= 0) return false;
+  return (currentTokens / contextWindow) >= threshold;
+}
+
+/**
+ * Check if an error represents a context overflow.
+ * Matches common API error patterns from various providers.
+ */
+export function isContextOverflow(error: Error): boolean {
+  const msg = error.message.toLowerCase();
+  return (
+    msg.includes('context_length_exceeded') ||
+    msg.includes('context window') ||
+    msg.includes('maximum context length') ||
+    msg.includes('token limit') ||
+    msg.includes('too many tokens') ||
+    msg.includes('request too large') ||
+    msg.includes('prompt is too long') ||
+    msg.includes('input too long')
+  );
+}