Add conversation history compaction start event and enhance compaction metrics

[aantn]

Summary

Enhanced the conversation history compaction feature by adding a new conversation_history_compaction_start event and significantly expanding the metadata and diagnostics provided in the conversation_history_compacted event.

Key Changes

• New Event: Added CONVERSATION_HISTORY_COMPACTION_START stream event that fires before compaction begins, allowing clients to display loading states with context about the current conversation state (token count, message count, context window usage)

• Enhanced Compaction Event: Expanded conversation_history_compacted event payload with:

  • compaction_summary: The LLM-generated summary text wrapped in <analysis> tags for debugging and verification
  • Comprehensive metadata including compression ratio percentage, message counts before/after, and context window details
  • Optional compaction_cost object with detailed token usage and dollar cost of the compaction LLM call

• Improved Diagnostics: Added calculation and reporting of:

  • Compression ratio percentage (e.g., 46.7% reduction)
  • Message count before and after compaction
  • Context window threshold percentage that triggered compaction
  • Full cost breakdown of the compaction operation

• Updated Event Sequence: Modified the documented event flow to include the new compaction start event and an ai_message notification after compaction completes

Implementation Details

• The compaction start event is emitted immediately before the compact_conversation_history() call with current conversation metrics
• The compaction summary is extracted from the assistant message in the compacted message history
• All metadata is collected into a single compaction_stats dictionary for consistency
• Cost information is conditionally included only when compaction_usage data is available

https://claude.ai/code/session_01Pmypw4hEkVU9pXgdd6j8Hq

Summary by CodeRabbit

• New Features

  • Added an event to signal the start of conversation history compaction, reporting initial tokens and message counts.

• Enhancements

  • Enriched the compaction-completed event with compaction_summary, compression ratio %, messages before/after, max context and threshold, and optional compaction cost breakdown.
  • Updated example event flow to include the new start and enriched compaction events.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b04ed182-18c5-41e8-99cb-7df27f175548

📥 Commits

Reviewing files that changed from the base of the PR and between 134c5b1 and be8704c.

📒 Files selected for processing (1)

• docs/reference/http-api.md

---

Walkthrough

Added instrumentation for conversation history compaction: a new conversation_history_compaction_start event is emitted before compaction; conversation_history_compacted now carries compaction_summary, expanded metadata (compression ratio, message counts, thresholds, optional compaction_cost), docs updated, and an enum entry added.

Changes

Cohort / File(s)	Summary
Documentation Updates docs/reference/http-api.md	Added conversation_history_compaction_start event docs and payload; expanded conversation_history_compacted payload with compaction_summary and detailed metadata fields (compression_ratio_pct, num_messages_before/after, max_context_size, threshold_pct, compaction_cost). Updated example event flow to include the new start event.
Compaction Instrumentation holmes/core/truncation/input_context_window_limiter.py	Emit CONVERSATION_HISTORY_COMPACTION_START before running compaction; perform compaction, capture usage and compaction summary, compute compression_ratio and message counts, populate compaction_stats/compaction_cost, emit enriched CONVERSATION_HISTORY_COMPACTED, and emit an AI_MESSAGE containing the compaction notice when successful.
Event Enum holmes/utils/stream.py	Added enum member CONVERSATION_HISTORY_COMPACTION_START = "conversation_history_compaction_start" to StreamEvents.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Limiter as InputContextWindowLimiter
    participant Events as Stream/EventEmitter
    participant LLM as LLM/Compaction
    participant Output as Client Stream

    Client->>Limiter: limit_input_context_window(messages, tokens)
    Note over Limiter: Determine if compaction needed

    Limiter->>Events: emit(conversation_history_compaction_start {initial_tokens, num_messages, max_context_size, threshold_pct})
    Events->>Output: conversation_history_compaction_start

    Limiter->>LLM: request compaction (history)
    LLM-->>Limiter: compaction_text + usage (tokens)

    Note over Limiter: compute compression_ratio_pct, num_messages_before/after, compaction_summary, compaction_cost

    Limiter->>Events: emit(conversation_history_compacted {compaction_summary, content, metadata: compaction_stats})
    Events->>Output: conversation_history_compacted

    Limiter->>Events: emit(ai_message (compaction notice))
    Events->>Output: ai_message

    Limiter-->>Client: return updated/compacted messages

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly Related PRs

• ROB-2405: document stream events #1073: Adds/updates streaming compaction events and documentation that overlap with these SSE event changes.

Suggested Reviewers

• moshemorad
• arikalon1

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main changes: adding a new conversation history compaction start event and enhancing compaction metrics across the codebase.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

✅ Docker images ready for 0a744ada (built in 2m 24s)

• us-central1-docker.pkg.dev/robusta-development/temporary-builds/holmes:0a744ada
• us-central1-docker.pkg.dev/robusta-development/temporary-builds/holmes-operator:0a744ada

⚠️ Warning: does not support ARM (ARM images are built on release only - not on every PR)

Use these tags to pull the images for testing.

📋 Copy commands

⚠️ Temporary images are deleted after 30 days. Copy to a permanent registry before using them:

gcloud auth configure-docker us-central1-docker.pkg.dev
docker pull us-central1-docker.pkg.dev/robusta-development/temporary-builds/holmes:0a744ada
docker tag us-central1-docker.pkg.dev/robusta-development/temporary-builds/holmes:0a744ada me-west1-docker.pkg.dev/robusta-development/development/holmes-dev:0a744ada
docker push me-west1-docker.pkg.dev/robusta-development/development/holmes-dev:0a744ada
docker pull us-central1-docker.pkg.dev/robusta-development/temporary-builds/holmes-operator:0a744ada
docker tag us-central1-docker.pkg.dev/robusta-development/temporary-builds/holmes-operator:0a744ada me-west1-docker.pkg.dev/robusta-development/development/holmes-operator-dev:0a744ada
docker push me-west1-docker.pkg.dev/robusta-development/development/holmes-operator-dev:0a744ada

Patch Helm values in one line (choose the chart you use):

HolmesGPT chart:

helm upgrade --install holmesgpt ./helm/holmes \
  --set registry=me-west1-docker.pkg.dev/robusta-development/development \
  --set image=holmes-dev:0a744ada \
  --set operator.registry=me-west1-docker.pkg.dev/robusta-development/development \
  --set operator.image=holmes-operator-dev:0a744ada

Robusta wrapper chart:

helm upgrade --install robusta robusta/robusta \
  --reuse-values \
  --set holmes.registry=me-west1-docker.pkg.dev/robusta-development/development \
  --set holmes.image=holmes-dev:0a744ada \
  --set holmes.operator.registry=me-west1-docker.pkg.dev/robusta-development/development \
  --set holmes.operator.image=holmes-operator-dev:0a744ada