Skip to content

LeoYeAI/agent-master-skills / skills/agent-mode-upgrades

agentic-loop-upgrade

Flagged

Enhanced agentic loop with planning, parallel execution, confidence gates, semantic error recovery, and observable state machine. Includes Mode dashboard UI for easy configuration.

src/context/summarizer.ts

View on GitHub
/**
 * Context Summarization
 * 
 * Manages context window by summarizing old content when
 * the conversation history grows too long.
 */

import type { LLMCaller } from "../types.js";

// ============================================================================
// Types
// ============================================================================

export interface Message {
  role: "user" | "assistant" | "system" | "tool";
  content: string;
  toolName?: string;
  toolResult?: unknown;
  timestamp?: number;
}

export interface SummarizerConfig {
  /** Enable automatic summarization */
  enabled: boolean;
  /** Target token count after summarization */
  targetTokens: number;
  /** Trigger summarization when exceeding this */
  thresholdTokens: number;
  /** Minimum messages to keep unsummarized */
  keepRecentMessages: number;
  /** Include tool results in summary */
  summarizeToolResults: boolean;
}

export interface SummarizationResult {
  summarized: boolean;
  summary?: string;
  removedMessages: number;
  originalTokens: number;
  finalTokens: number;
  savedTokens: number;
}

export interface ContextState {
  messages: Message[];
  summaries: ContextSummary[];
  totalTokensEstimate: number;
}

export interface ContextSummary {
  id: string;
  createdAt: number;
  messageRange: { from: number; to: number };
  summary: string;
  keyPoints: string[];
  tokensSaved: number;
}

// ============================================================================
// Token Estimation
// ============================================================================

/**
 * Rough token estimation (4 chars ≈ 1 token)
 */
export function estimateTokens(text: string): number {
  return Math.ceil(text.length / 4);
}

export function estimateMessageTokens(message: Message): number {
  let tokens = estimateTokens(message.content);
  tokens += 4; // Role overhead
  if (message.toolName) tokens += estimateTokens(message.toolName) + 2;
  if (message.toolResult) tokens += estimateTokens(JSON.stringify(message.toolResult));
  return tokens;
}

export function estimateTotalTokens(messages: Message[]): number {
  return messages.reduce((sum, m) => sum + estimateMessageTokens(m), 0);
}

// ============================================================================
// Context Summarizer
// ============================================================================

const DEFAULT_CONFIG: SummarizerConfig = {
  enabled: true,
  targetTokens: 50000,
  thresholdTokens: 80000,
  keepRecentMessages: 10,
  summarizeToolResults: true,
};

export class ContextSummarizer {
  private config: SummarizerConfig;
  private llmCaller?: LLMCaller;
  private summaries: ContextSummary[] = [];

  constructor(config: Partial<SummarizerConfig> = {}, llmCaller?: LLMCaller) {
    this.config = { ...DEFAULT_CONFIG, ...config };
    this.llmCaller = llmCaller;
  }

  /**
   * Check if summarization is needed
   */
  needsSummarization(messages: Message[]): boolean {
    if (!this.config.enabled) return false;
    const totalTokens = estimateTotalTokens(messages);
    return totalTokens > this.config.thresholdTokens;
  }

  /**
   * Summarize older messages to reduce context size
   */
  async summarize(messages: Message[]): Promise<SummarizationResult> {
    const originalTokens = estimateTotalTokens(messages);
    
    if (!this.needsSummarization(messages)) {
      return {
        summarized: false,
        removedMessages: 0,
        originalTokens,
        finalTokens: originalTokens,
        savedTokens: 0,
      };
    }

    // Determine how many messages to summarize
    const keepCount = Math.max(this.config.keepRecentMessages, 3);
    const recentMessages = messages.slice(-keepCount);
    const olderMessages = messages.slice(0, -keepCount);

    if (olderMessages.length < 3) {
      // Not enough to summarize meaningfully
      return {
        summarized: false,
        removedMessages: 0,
        originalTokens,
        finalTokens: originalTokens,
        savedTokens: 0,
      };
    }

    // Generate summary
    const summary = await this.generateSummary(olderMessages);
    
    // Create summary record
    const summaryRecord: ContextSummary = {
      id: `sum_${Date.now()}`,
      createdAt: Date.now(),
      messageRange: { from: 0, to: olderMessages.length - 1 },
      summary: summary.text,
      keyPoints: summary.keyPoints,
      tokensSaved: estimateTotalTokens(olderMessages) - estimateTokens(summary.text),
    };
    
    this.summaries.push(summaryRecord);

    const finalTokens = estimateTokens(summary.text) + estimateTotalTokens(recentMessages);

    return {
      summarized: true,
      summary: summary.text,
      removedMessages: olderMessages.length,
      originalTokens,
      finalTokens,
      savedTokens: originalTokens - finalTokens,
    };
  }

  /**
   * Get summary to inject as context
   */
  getSummaryContext(): string {
    if (this.summaries.length === 0) return "";

    const latest = this.summaries[this.summaries.length - 1];
    return `
## Previous Conversation Summary

${latest.summary}

### Key Points
${latest.keyPoints.map(p => `- ${p}`).join("\n")}

_This summarizes ${latest.messageRange.to - latest.messageRange.from + 1} earlier messages._
`.trim();
  }

  /**
   * Condense tool results to save tokens
   */
  condenseToolResult(result: unknown, maxTokens: number = 500): string {
    const str = typeof result === "string" ? result : JSON.stringify(result, null, 2);
    const tokens = estimateTokens(str);
    
    if (tokens <= maxTokens) return str;

    // Truncate intelligently
    const lines = str.split("\n");
    let condensed = "";
    let currentTokens = 0;
    
    for (const line of lines) {
      const lineTokens = estimateTokens(line);
      if (currentTokens + lineTokens > maxTokens - 50) {
        condensed += "\n... [truncated] ...";
        break;
      }
      condensed += (condensed ? "\n" : "") + line;
      currentTokens += lineTokens;
    }

    return condensed;
  }

  /**
   * Build optimized message array with summarization
   */
  async optimizeMessages(messages: Message[]): Promise<{
    messages: Message[];
    summaryInjected: boolean;
  }> {
    if (!this.needsSummarization(messages)) {
      return { messages, summaryInjected: false };
    }

    const result = await this.summarize(messages);
    
    if (!result.summarized || !result.summary) {
      return { messages, summaryInjected: false };
    }

    // Create new message array with summary + recent messages
    const keepCount = this.config.keepRecentMessages;
    const recentMessages = messages.slice(-keepCount);
    
    const summaryMessage: Message = {
      role: "system",
      content: `[Context Summary]\n${result.summary}`,
      timestamp: Date.now(),
    };

    return {
      messages: [summaryMessage, ...recentMessages],
      summaryInjected: true,
    };
  }

  // ──────────────────────────────────────────────────────────────────────────
  // Private Methods
  // ──────────────────────────────────────────────────────────────────────────

  private async generateSummary(messages: Message[]): Promise<{
    text: string;
    keyPoints: string[];
  }> {
    if (this.llmCaller) {
      return this.llmGenerateSummary(messages);
    }
    return this.heuristicSummary(messages);
  }

  private async llmGenerateSummary(messages: Message[]): Promise<{
    text: string;
    keyPoints: string[];
  }> {
    const conversationText = messages.map(m => {
      let content = `[${m.role}]: ${m.content.slice(0, 500)}`;
      if (m.toolName) content += ` (tool: ${m.toolName})`;
      return content;
    }).join("\n\n");

    const prompt = `Summarize this conversation concisely, preserving key decisions, results, and context needed for continuation.

Conversation:
${conversationText.slice(0, 8000)}

Respond in JSON:
{
  "summary": "2-3 paragraph summary",
  "keyPoints": ["point 1", "point 2", ...]
}`;

    try {
      const response = await this.llmCaller!({
        messages: [
          { role: "system", content: "You summarize conversations. Output valid JSON." },
          { role: "user", content: prompt },
        ],
        maxTokens: 800,
      });

      const parsed = JSON.parse(response.content);
      return {
        text: parsed.summary || "Conversation summary unavailable.",
        keyPoints: parsed.keyPoints || [],
      };
    } catch {
      return this.heuristicSummary(messages);
    }
  }

  private heuristicSummary(messages: Message[]): {
    text: string;
    keyPoints: string[];
  } {
    // Extract key information heuristically
    const userMessages = messages.filter(m => m.role === "user");
    const toolCalls = messages.filter(m => m.role === "tool" || m.toolName);
    const decisions = messages.filter(m => 
      m.content.toLowerCase().includes("decided") ||
      m.content.toLowerCase().includes("will ") ||
      m.content.toLowerCase().includes("let's ")
    );

    const keyPoints: string[] = [];
    
    // First user message often contains the goal
    if (userMessages[0]) {
      keyPoints.push(`Initial request: ${userMessages[0].content.slice(0, 100)}...`);
    }

    // Note tool usage
    if (toolCalls.length > 0) {
      const toolNames = [...new Set(toolCalls.map(t => t.toolName).filter(Boolean))];
      keyPoints.push(`Tools used: ${toolNames.join(", ")}`);
    }

    // Extract decisions
    decisions.slice(0, 3).forEach(d => {
      const snippet = d.content.slice(0, 80);
      keyPoints.push(snippet + (d.content.length > 80 ? "..." : ""));
    });

    const summary = `This conversation covered ${messages.length} exchanges. ` +
      `The user made ${userMessages.length} requests. ` +
      `${toolCalls.length} tool operations were performed. ` +
      `Key context has been preserved below.`;

    return { text: summary, keyPoints };
  }
}

// ============================================================================
// Factory
// ============================================================================

export function createContextSummarizer(
  config?: Partial<SummarizerConfig>,
  llmCaller?: LLMCaller
): ContextSummarizer {
  return new ContextSummarizer(config, llmCaller);
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall