novacode-cli 1.2.0__py3-none-any.whl

novacode_cli/compaction.py

@@ -0,0 +1,753 @@
+"""Conversation compaction and summarization for NovaCode-cli.
+
+This module provides functionality to compress conversation history
+by generating an intelligent summary that preserves key context.
+"""
+
+import asyncio
+import hashlib
+import json
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, RemoveMessage, ToolMessage
+from langgraph.graph.message import REMOVE_ALL_MESSAGES
+
+from novacode_cli.context import CompactionResult
+from novacode_cli.prompts import render_template
+
+# Summarization prompt template (loaded from Jinja)
+# Template file: NovaCode_cli/prompts/summarization.jinja
+
+# Compaction rewrites the whole conversation into ONE synthetic HumanMessage
+# carrying the summary (see compact_conversation). It has to be a HumanMessage
+# for the provider's turn ordering, but it is not something the user said — so
+# any surface that renders history must skip it, or the entire summarized
+# context appears in the transcript as a message the user supposedly typed.
+COMPACTION_SUMMARY_MARKER = "[Conversation context — previous session summarized]"
+
+logger = logging.getLogger(__name__)
+SUMMARY_TIMEOUT_SECONDS = 60.0
+SUMMARY_ATTEMPTS = 3
+
+
+async def _summary_call(model: BaseChatModel, prompt: str, purpose: str) -> BaseMessage:
+    """Preserve each independent summary request and label its actual dispatch."""
+    from novacode_cli.tracking.request_metrics import dispatch
+
+    with dispatch(purpose):
+        response = await model.ainvoke([HumanMessage(content=prompt)])
+    if getattr(response, "tool_calls", None) or getattr(response, "invalid_tool_calls", None):
+        message = "Summary provider returned tool calls"
+        raise SummaryUnavailableError(message)
+    return response
+
+
+def _state_generation(state: Any) -> str:  # noqa: ANN401 - compiled graph state is framework-defined
+    """Fingerprint checkpoint and complete messages before preparing a rewrite."""
+    data = {
+        "checkpoint": getattr(state, "config", None),
+        "messages": [m.model_dump(mode="json") for m in state.values.get("messages", [])],
+        "summarization_event": state.values.get("_summarization_event"),
+    }
+    return hashlib.sha256(json.dumps(data, sort_keys=True, default=str).encode()).hexdigest()
+
+
+def _validate_generation(state: Any, expected: str) -> None:  # noqa: ANN401 - custom graph state
+    """Discard a prepared summary whose source checkpoint was superseded."""
+    if _state_generation(state) != expected:
+        message = "Conversation changed during compaction; original history retained"
+        raise SummaryUnavailableError(message)
+
+
+class SummaryUnavailableError(RuntimeError):
+    """The provider could not produce a usable compaction summary."""
+
+    def __init__(self, message: str = "Provider returned an empty response") -> None:
+        """Describe a failed or empty summarization response."""
+        super().__init__(message)
+
+
+def is_compaction_summary(text: str) -> bool:
+    """True if *text* is the synthetic message compaction injects."""
+    return text.lstrip().startswith(COMPACTION_SUMMARY_MARKER)
+
+
+def _format_message_content(content: Any) -> str:
+    """Format message content to a string.
+
+    Handles both string content and content blocks (list of dicts).
+
+    Args:
+        content: The message content (str or list of content blocks)
+
+    Returns:
+        Formatted string representation
+    """
+    if isinstance(content, str):
+        return content
+
+    if isinstance(content, list):
+        # Handle content blocks (e.g., from Claude)
+        text_parts = []
+        for block in content:
+            if isinstance(block, dict):
+                if block.get("type") == "text":
+                    text_parts.append(block.get("text", ""))
+                elif block.get("type") == "tool_use":
+                    tool_name = block.get("name", "unknown_tool")
+                    text_parts.append(f"[Called tool: {tool_name}]")
+            elif isinstance(block, str):
+                text_parts.append(block)
+        return " ".join(text_parts)
+
+    return str(content)
+
+
+def _message_parts(messages: list[BaseMessage]) -> list[str]:
+    """Render each message to a compact ``ROLE: text`` line (per-message truncation)."""
+    parts: list[str] = []
+    for msg in messages:
+        if isinstance(msg, HumanMessage):
+            # An earlier summary being folded into a new one goes in whole: cut
+            # to 2,000 characters like a user message, everything it carried
+            # from before the previous compaction would be lost at this one.
+            earlier = msg.additional_kwargs.get("nova_summary")
+            if earlier:
+                parts.append(f"EARLIER SUMMARY (carry its facts forward):\n{earlier}")
+                continue
+            content = _format_message_content(msg.content)
+            if len(content) > 2000:
+                content = content[:2000] + "... [truncated]"
+            parts.append(f"USER: {content}")
+        elif isinstance(msg, AIMessage):
+            content = _format_message_content(msg.content)
+            if len(content) > 2000:
+                content = content[:2000] + "... [truncated]"
+            # Tool calls live in .tool_calls, not .content — on a tool-calling
+            # turn the content is usually empty, so without this the summarizer
+            # never saw WHICH file was edited or WHAT command ran, and "Files
+            # Modified" was guessed from truncated tool results.
+            calls = [_render_tool_call(tc) for tc in getattr(msg, "tool_calls", None) or []]
+            parts.append("ASSISTANT: " + "\n".join(filter(None, [content, *calls])))
+        elif isinstance(msg, ToolMessage):
+            content = _format_message_content(msg.content)
+            if len(content) > 500:
+                content = content[:500] + "... [truncated]"
+            parts.append(f"TOOL({msg.name}): {content}")
+    return parts
+
+
+_TOOL_ARGS_CHARS = 300
+
+
+def _render_tool_call(call: dict) -> str:
+    """Render a tool call as ``-> name({args})`` with the args capped.
+
+    Enough for the summarizer to know what was touched, not a copy of the payload.
+    """
+    args = json.dumps(call.get("args") or {}, ensure_ascii=False, default=str)
+    if len(args) > _TOOL_ARGS_CHARS:
+        args = args[:_TOOL_ARGS_CHARS] + "...}"
+    return f"-> {call.get('name', 'tool')}({args})"
+
+
+def _window_tokens(model: BaseChatModel, context_window: int | None = None) -> int:
+    """Return the model's context window in tokens.
+
+    The caller's value wins (the TUI passes the tracker's effective window,
+    which accounts for Ollama ``num_ctx``); else the static table
+    (``use_dynamic=False`` — no slow/flaky live query here).
+    """
+    if context_window and context_window > 0:
+        return context_window
+    name = getattr(model, "model_name", None) or getattr(model, "model", None) or ""
+    try:
+        from novacode_cli.context._analysis import get_context_window_size
+
+        return get_context_window_size(str(name), use_dynamic=False)
+    except Exception:  # noqa: BLE001
+        return 8192
+
+
+def _budget_chars(model: BaseChatModel, context_window: int | None = None) -> int:
+    """Character budget for the summarizer's input, sized to the model's context
+    window so a long conversation never overflows the summarization call itself.
+
+    Reserves ~45% of the window for the prompt template + generated summary;
+    rough 4-chars/token.
+    """
+    return max(8000, int(_window_tokens(model, context_window) * 0.55) * 4)
+
+
+# The recent tail compaction keeps VERBATIM, as a share of the window, capped.
+# Codex keeps ~20k tokens of recent messages; deepagents' own summarizer keeps
+# 10% of the window. Summarizing the turn the agent is in the middle of is the
+# lossiest possible cut — the exact error text, the file just edited, the
+# user's latest wording all become a paraphrase.
+KEEP_TAIL_FRACTION = 0.10
+KEEP_TAIL_MAX_TOKENS = 20_000
+
+
+def _message_chars(msg: BaseMessage) -> int:
+    size = len(_format_message_content(msg.content))
+    for call in getattr(msg, "tool_calls", None) or []:
+        size += len(json.dumps(call.get("args") or {}, default=str))
+    return size
+
+
+def _split_tail(messages: list[BaseMessage], keep_tokens: int) -> int:
+    """Index where the verbatim tail starts (``len(messages)`` = keep nothing).
+
+    Cuts only at a real user message, so a tool call is never separated from
+    its result, and takes the EARLIEST such cut whose tail fits the budget. A
+    tail with a ToolMessage whose call is not in the tail is rejected as a
+    second guard (a steer injected mid-turn is also a HumanMessage).
+    """
+    budget = keep_tokens * 4
+    best = len(messages)
+    size = 0
+    for i in range(len(messages) - 1, 0, -1):  # index 0: nothing left to summarize
+        size += _message_chars(messages[i])
+        if size > budget:
+            break
+        msg = messages[i]
+        if isinstance(msg, HumanMessage) and not is_compaction_summary(
+            _format_message_content(msg.content)
+        ):
+            best = i
+    tail = messages[best:]
+    issued = {tc.get("id") for m in tail for tc in (getattr(m, "tool_calls", None) or [])}
+    if any(isinstance(m, ToolMessage) and m.tool_call_id not in issued for m in tail):
+        return len(messages)
+    return best
+
+
+def _rehydration_note() -> str:
+    """Paths the agent touched, so it can re-read them just in time.
+
+    Claude Code and Codex re-attach recently used files after compacting. Paths
+    are the cheap form of that: the content is on disk, the summary only has
+    to say where to look.
+    """
+    try:
+        from novacode_cli.tracking.file_tracker import (
+            get_modified_files,
+            get_recently_read_files,
+        )
+
+        modified = get_modified_files()[-15:]
+        read = [p for p in get_recently_read_files(15) if p not in modified]
+    except Exception:  # noqa: BLE001 — a hint, never worth failing compaction
+        return ""
+    lines = []
+    if modified:
+        lines.append("- Modified: " + ", ".join(modified))
+    if read:
+        lines.append("- Read recently: " + ", ".join(read))
+    if not lines:
+        return ""
+    return (
+        "## Files touched this session\n"
+        "Re-read a file before relying on its contents; the summary only "
+        "describes it.\n" + "\n".join(lines)
+    )
+
+
+def _continuation_framing(*, tail_kept: bool) -> str:
+    """Mark compacted requests as history, with the current tail taking precedence."""
+    tail = (
+        "The verbatim tail after this summary is authoritative for current progress. "
+        if tail_kept
+        else "Use the latest recorded state to determine current progress. "
+    )
+    return (
+        "The earlier conversation was compacted into the summary below. "
+        + tail
+        + "Continue the work only if it is unfinished, from the last observed action. "
+        "Do not repeat completed steps or tool calls. Do not acknowledge or restate this summary."
+    )
+
+
+def _historical_user_requests(requests: list[str]) -> str:
+    """Preserve earlier user words without presenting completed requests as new turns."""
+    if not requests:
+        return ""
+    return (
+        "## Earlier user requests and constraints (historical context)\n\n"
+        "Keep applicable constraints, but do not assume these requests are still pending. "
+        "The summary and any verbatim tail record what was already completed.\n\n"
+        + "\n\n".join(f"{index}. {text}" for index, text in enumerate(requests, 1))
+    )
+
+
+def _archive_messages(thread_id: str, messages: list[BaseMessage]) -> Path | None:
+    """Write the pre-compaction transcript to the session dir; return its path.
+
+    Compaction is the one irreversible step in the context pipeline: the
+    summary is a paraphrase and the originals are replaced. LangGraph keeps the
+    old checkpoint, but nothing surfaces it — so the raw messages also go to a
+    file next to the session, the way Claude Code keeps a pre-compaction
+    transcript. Reaped with the session directory. Best-effort.
+    """
+    try:
+        from novacode_cli.context.archives import default_recovery_store
+        return default_recovery_store().archive(thread_id, messages)
+    except Exception:
+        logger.debug("Could not publish recovery archive", exc_info=True)
+        return None
+
+
+def _chunk_parts(parts: list[str], max_chars: int) -> list[list[str]]:
+    """Group formatted parts into chunks each within ``max_chars``."""
+    chunks: list[list[str]] = []
+    cur: list[str] = []
+    cur_len = 0
+    for p in parts:
+        if len(p) > max_chars:  # a single oversized part — hard-truncate it
+            p = p[:max_chars] + "... [truncated]"
+        if cur and cur_len + len(p) + 2 > max_chars:
+            chunks.append(cur)
+            cur, cur_len = [], 0
+        cur.append(p)
+        cur_len += len(p) + 2
+    if cur:
+        chunks.append(cur)
+    return chunks
+
+
+async def _summarize_text(
+    model: BaseChatModel,
+    conversation_text: str,
+    focus_instructions: str | None,
+    *,
+    tail_kept: bool = False,
+) -> str:
+    """One summarization LLM call over ``conversation_text``."""
+    if focus_instructions:
+        focus_text = (
+            f"\n**IMPORTANT - User requested focus on**: {focus_instructions}\n\n"
+            "Make sure to especially preserve information related to this focus area.\n"
+        )
+    else:
+        focus_text = ""
+    prompt = render_template(
+        "summarization.jinja",
+        focus_instructions=focus_text,
+        conversation=conversation_text,
+        tail_kept=tail_kept,
+    )
+    from novacode_cli.errors import is_retryable_model_error
+
+    for attempt in range(SUMMARY_ATTEMPTS):
+        try:
+            response = await asyncio.wait_for(
+                _summary_call(model, prompt, "summary.generate"), SUMMARY_TIMEOUT_SECONDS
+            )
+            summary = _format_message_content(response.content).strip()
+            if not summary:
+                raise SummaryUnavailableError()  # noqa: TRY301 - retry empty output
+            return summary  # noqa: TRY300
+        except Exception as error:
+            if not is_retryable_model_error(error):
+                raise
+            if attempt + 1 == SUMMARY_ATTEMPTS:
+                message = (
+                    "The summary provider is unavailable after 3 attempts. "
+                    "Conversation history was kept. Try /compact again shortly "
+                    "or switch models with /model."
+                )
+                raise SummaryUnavailableError(message) from error
+            logger.debug("Retrying compaction summary", exc_info=True)
+            await asyncio.sleep(2**attempt)
+    message = "No summary attempts configured"
+    raise AssertionError(message)
+
+
+def _answer_budget(budget: int, questions: str) -> int:
+    """Conversation budget for the answer pass (reserve room for questions + template)."""
+    return max(1000, budget - len(questions) - 500)
+
+
+async def _generate_questions(model: BaseChatModel, summary: str) -> str:
+    """One LLM call: read the summary and ask what important details are missing."""
+    prompt = render_template("summarization_questions.jinja", summary=summary)
+    response = await _summary_call(model, prompt, "summary.questions")
+    return _format_message_content(response.content).strip()
+
+
+async def _answer_questions(
+    model: BaseChatModel, questions: str, parts: list[str], budget: int
+) -> str:
+    """Answer the clarifying questions from the full conversation.
+
+    Fits in one call when the conversation does; otherwise answers per chunk
+    and merges the per-chunk answers into one consolidated Q&A block.
+    """
+    text = "\n\n".join(parts)
+    q_budget = _answer_budget(budget, questions)
+    if len(text) <= q_budget:
+        prompt = render_template(
+            "summarization_answers.jinja", questions=questions, conversation=text
+        )
+        response = await _summary_call(model, prompt, "summary.answers")
+        return _format_message_content(response.content).strip()
+
+    per_chunk: list[str] = []
+    for chunk in _chunk_parts(parts, q_budget):
+        prompt = render_template(
+            "summarization_answers.jinja",
+            questions=questions,
+            conversation="\n\n".join(chunk),
+        )
+        response = await _summary_call(model, prompt, "summary.chunk_answers")
+        per_chunk.append(_format_message_content(response.content).strip())
+
+    # Merge: consolidate the per-chunk answers into one Q&A block (bounded).
+    merged = "\n\n".join(
+        f"## Excerpt {i + 1} of {len(per_chunk)}\n{a}" for i, a in enumerate(per_chunk)
+    )
+    prompt = render_template(
+        "summarization_answers.jinja",
+        questions=questions,
+        conversation=merged[:q_budget],
+    )
+    response = await _summary_call(model, prompt, "summary.merge_answers")
+    return _format_message_content(response.content).strip()
+
+
+async def _qa_refine(model: BaseChatModel, summary: str, parts: list[str], budget: int) -> str:
+    """Gap-fill a lossy summary: ask what it missed, restore it from the source.
+
+    Best-effort — any failure returns ``""`` so compaction falls back to the
+    plain summary. Returns the Q&A block to append, or ``""`` when nothing
+    is missing.
+    """
+    try:
+        questions = await _generate_questions(model, summary)
+        if not questions or "NONE" in questions.upper():
+            return ""
+        answers = await _answer_questions(model, questions, parts, budget)
+        if not answers.strip():
+            return ""
+        return f"## Clarifying Q&A\n\n{answers.strip()}"
+    except Exception:  # noqa: BLE001 — refinement must never break compaction
+        return ""
+
+
+async def summarize_conversation(
+    model: BaseChatModel,
+    messages: list[BaseMessage],
+    focus_instructions: str | None = None,
+    context_window: int | None = None,
+    *,
+    tail_kept: bool = False,
+) -> str:
+    """Summarize a conversation, budgeted to the model's context window.
+
+    Short conversations are summarized in a single call. Long ones (that would
+    overflow the summarizer's own window — exactly when compaction matters most)
+    are summarized **hierarchically**: chunk → summarize each chunk → summarize
+    the chunk-summaries into one cohesive summary, recursing if still too large.
+    The hierarchical path then runs a **Q&A gap-filling pass** (Meta-Harness
+    port): a second call reads the summary and asks what important details are
+    missing, and a third answers those questions from the full conversation —
+    recovering details a single lossy pass drops. Best-effort: any failure falls
+    back to the plain summary.
+
+    Args:
+        model: The LLM to use for summarization
+        messages: The conversation messages to summarize
+        focus_instructions: Optional focus instructions from the user
+        context_window: Optional explicit context window (tokens); the TUI passes
+            the token tracker's effective window.
+        tail_kept: The most recent messages stay verbatim after the summary, so
+            the summary covers only what precedes them.
+
+    Returns:
+        The summarized conversation as a string
+
+    Raises:
+        Exception: If the LLM call fails
+    """
+    parts = _message_parts(messages)
+    budget = _budget_chars(model, context_window)
+    text = "\n\n".join(parts)
+
+    if len(text) <= budget:
+        return await _summarize_text(model, text, focus_instructions, tail_kept=tail_kept)
+
+    # Too big for one call → hierarchical summarization.
+    chunks = _chunk_parts(parts, budget)
+    summaries: list[str] = []
+    for i, chunk in enumerate(chunks):
+        s = await _summarize_text(model, "\n\n".join(chunk), focus_instructions)
+        summaries.append(f"## Part {i + 1} of {len(chunks)}\n{s}")
+    combined = "\n\n".join(summaries)
+
+    # If even the combined chunk-summaries are too large, collapse them further.
+    depth = 0
+    while len(combined) > budget and depth < 3:
+        depth += 1
+        summaries = [
+            await _summarize_text(model, "\n\n".join(group), focus_instructions)
+            for group in _chunk_parts(combined.split("\n\n"), budget)
+        ]
+        combined = "\n\n".join(summaries)
+
+    # Final pass: one cohesive summary from the collapsed material.
+    final = await _summarize_text(model, combined[:budget], focus_instructions, tail_kept=tail_kept)
+
+    # Q&A gap-filling (Meta-Harness port): the hierarchical path is lossy — ask
+    # what the summary missed and restore it from the full conversation. Only
+    # here: short single-pass summaries are already high-fidelity.
+    qa = await _qa_refine(model, final, parts, budget)
+    if qa:
+        final = f"{final}\n\n{qa}"
+    return final
+
+
+async def compact_conversation(
+    agent: Any,
+    model: BaseChatModel,
+    thread_id: str,
+    focus_instructions: str | None = None,
+    context_window: int | None = None,
+    agent_dir: Path | None = None,
+) -> CompactionResult:
+    """Prepare a generation-validated rewrite with correlated summary requests."""
+    from novacode_cli.computation_cache import digest
+    from novacode_cli.tracking.request_metrics import correlate
+
+    with correlate(digest(thread_id)):
+        return await _compact_conversation(
+            agent, model, thread_id, focus_instructions, context_window, agent_dir
+        )
+
+
+async def _compact_conversation(
+    agent: Any,  # noqa: ANN401 - custom compiled graphs share a duck-typed state API
+    model: BaseChatModel,
+    thread_id: str,
+    focus_instructions: str | None = None,
+    context_window: int | None = None,
+    agent_dir: Path | None = None,
+) -> CompactionResult:
+    """Compact a conversation by summarizing and replacing history.
+
+    This function:
+    1. Retrieves the current conversation history
+    2. Generates a summary using the LLM
+    3. Replaces the conversation with a single summary message
+
+    Args:
+        agent: The LangGraph agent
+        model: The LLM model for summarization
+        thread_id: The thread/session ID
+        focus_instructions: Optional user instructions for what to preserve
+        context_window: Model context window (tokens) to budget the summary to
+        agent_dir: If given, the compaction summary is also persisted as a
+            durable memory lesson (``memories/session-summary.md``) so the
+            conversation's knowledge survives the rewrite.
+
+    Returns:
+        CompactionResult with details of the compaction operation
+    """
+    config = {"configurable": {"thread_id": thread_id}}
+
+    try:
+        # Get current state
+        state = await agent.aget_state(config)
+        generation = _state_generation(state)
+        messages = state.values.get("messages", [])
+
+        if not messages:
+            return CompactionResult(
+                success=False,
+                original_tokens=0,
+                new_tokens=0,
+                tokens_saved=0,
+                messages_before=0,
+                messages_after=0,
+                summary="",
+                error="No conversation history to compact.",
+            )
+
+        messages_before = len(messages)
+        from novacode_cli.agents.context_compaction import user_messages
+
+        protected_tokens = sum(max(1, len(text) // 3) for text in user_messages(messages, 0))
+        reservation = getattr(model, "max_tokens", None) or 0
+        if isinstance(reservation, int) and protected_tokens + reservation > _window_tokens(
+            model, context_window
+        ):
+            raise SummaryUnavailableError(
+                "Protected instructions exceed the usable context window. Select a larger model window or explicitly revise the task. Conversation history was kept."
+            )
+        # A long transcript is tens of MB of JSON; write it off the UI's loop.
+        archived = await asyncio.to_thread(_archive_messages, thread_id, messages)
+        if not archived:
+            raise SummaryUnavailableError(
+                "Compaction archive could not be saved. Conversation history was kept."
+            )
+        from novacode_cli.session.checkpoint_coordinator import CoordinatedGraph
+        if isinstance(agent, CoordinatedGraph):
+            from novacode_cli.context.archives import default_recovery_store
+            saver = agent.coordinator.saver
+            original = await saver.aget_tuple(state.config)
+            if original:
+                packed = {
+                    "checkpoint": saver.serde.dumps_typed(original.checkpoint),
+                    "pending": saver.serde.dumps_typed(original.pending_writes),
+                    "metadata": original.metadata,
+                }
+                archived = await asyncio.to_thread(
+                    default_recovery_store().archive,
+                    thread_id,
+                    messages,
+                    checkpoint=packed,
+                )
+
+        # These display statistics are estimates. Provider token counters may
+        # make synchronous network calls; use Nova's local, image-aware estimate.
+        from novacode_cli.context.estimates import estimate_content
+
+        original_tokens = (await asyncio.to_thread(estimate_content, messages)).total
+
+        # Keep the recent tail verbatim; summarize only what precedes it.
+        keep_tokens = min(
+            KEEP_TAIL_MAX_TOKENS,
+            int(_window_tokens(model, context_window) * KEEP_TAIL_FRACTION),
+        )
+        cut = _split_tail(messages, keep_tokens)
+        from novacode_cli.agents.context_compaction import pending_tool_start
+
+        cut = min(cut, pending_tool_start(messages))
+        if cut == 0:
+            raise SummaryUnavailableError(
+                "Pending tool calls prevent compaction. Resolve the pending approval or tool call first. Conversation history was kept."
+            )
+        head, tail = messages[:cut], messages[cut:]
+
+        # Generate summary (budgeted to the model's context window)
+        summary = await summarize_conversation(
+            model,
+            head,
+            focus_instructions,
+            context_window=context_window,
+            tail_kept=bool(tail),
+        )
+
+        # Replace the conversation in a single atomic update: REMOVE_ALL then
+        # summary + tail, so the summary lands BEFORE the tail (a plain
+        # RemoveMessage per id would append it after) and the state never
+        # passes through an invalid intermediate (ToolMessages with no
+        # AIMessage), which crashes langchain's _fetch_last_ai_and_tool_messages.
+        framing = _continuation_framing(tail_kept=bool(tail))
+        archive_note = (
+            f"The full pre-compaction transcript is at {archived} if an exact detail is needed."
+            if archived
+            else ""
+        )
+        from novacode_cli.agents.context_compaction import user_content_blocks, user_messages
+        from novacode_cli.context.task_progress import render_task_progress, task_progress
+
+        said = user_messages(head, 0)
+        progress = task_progress(head, state.values.get("todos"))
+        protected = _historical_user_requests(said)
+        body = "\n\n".join(
+            filter(None, [framing, protected, summary, render_task_progress(progress),
+                          _rehydration_note(), archive_note])
+        )
+        blocks = user_content_blocks(head)
+        content = f"{COMPACTION_SUMMARY_MARKER}\n\n{body}"
+        summary_message = HumanMessage(
+            content=[{"type": "text", "text": content}, *blocks] if blocks else content,
+            additional_kwargs={
+                "lc_source": "summarization",
+                "user_messages": said,
+                "nova_summary": summary,
+                "nova_task_progress": progress,
+                "history_files": [str(archived)] if archived else [],
+                "user_content_blocks": blocks,
+            },
+        )
+        # Also clear any prior auto-summarization event.
+        # ContextCompactionMiddleware reconstructs the effective message list from
+        # `_summarization_event` (a cutoff index into the OLD message list); if we
+        # rewrite messages without clearing it, the next turn would slice the new
+        # list at a stale index and corrupt context. Resetting it makes the fresh
+        # summary the whole context.
+        new_messages = [RemoveMessage(id=REMOVE_ALL_MESSAGES), summary_message, *tail]
+        update_values: dict[str, Any] = {
+            "messages": new_messages,
+            "_summarization_event": None,
+        }
+        current = await agent.aget_state(config)
+        _validate_generation(current, generation)
+        from novacode_cli.session.checkpoint_coordinator import CoordinatedGraph
+        commit_options = {}
+        if isinstance(agent, CoordinatedGraph):
+            commit_options["expected_revision"] = (state.config or {}).get("configurable", {}).get("checkpoint_id")
+        try:
+            await agent.aupdate_state(config=config, values=update_values, as_node="model", **commit_options)
+        except Exception:
+            # Older graphs without the summarization state key reject the extra
+            # field; retry with just the message rewrite.
+            current = await agent.aget_state(config)
+            _validate_generation(current, generation)
+            await agent.aupdate_state(
+                config=config,
+                values={"messages": new_messages},
+                as_node="model",
+                **commit_options,
+            )
+
+        new_tokens = (await asyncio.to_thread(estimate_content, [summary_message, *tail])).total
+
+        # Persist the summary as a durable memory lesson so the conversation's
+        # knowledge survives the rewrite (best-effort; never fails compaction).
+        learnings = ""
+        if agent_dir is not None:
+            try:
+                from novacode_cli.hermes.memory_tiers import record_lesson
+
+                # The marker travels WITH the artifact: a derived summary is
+                # injected into future prompts, so it must carry its own
+                # provenance rather than relying on an instruction elsewhere to
+                # establish precedence. Unlabelled, it reads as verified fact.
+                record_lesson(
+                    agent_dir,
+                    "session-summary",
+                    "[derived summary, not a verified record — may be incomplete; "
+                    "observed reality wins on any conflict]\n\n" + summary,
+                )
+                learnings = summary
+            except Exception:  # noqa: BLE001 — memory persistence is best-effort
+                learnings = ""
+
+        return CompactionResult(
+            success=True,
+            original_tokens=original_tokens,
+            new_tokens=new_tokens,
+            tokens_saved=max(0, original_tokens - new_tokens),
+            messages_before=messages_before,
+            messages_after=1 + len(tail),
+            summary=summary,
+            learnings=learnings,
+        )
+
+    except Exception as e:
+        return CompactionResult(
+            success=False,
+            original_tokens=0,
+            new_tokens=0,
+            tokens_saved=0,
+            messages_before=0,
+            messages_after=0,
+            summary="",
+            error=str(e),
+        )