Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

35.5 KB
Raw Blame
"""Build budgeted conversation history for unified chat sessions."""

from __future__ import annotations

from dataclasses import dataclass, field
import json
import logging
import os
import re
from typing import Any, Awaitable, Callable

from deeptutor.agents.base_agent import BaseAgent
from deeptutor.core.stream import StreamEvent, StreamEventType
from deeptutor.core.trace import build_trace_metadata, merge_trace_metadata, new_call_id
from deeptutor.services.llm.config import LLMConfig
from deeptutor.services.llm.context_window import (
    coerce_positive_int,
    resolve_effective_context_window,
)
from deeptutor.services.llm.image_replay import deduplicate_user_images
from deeptutor.services.llm.types import StreamOutcome
from deeptutor.services.prompt.language import language_label

from .ask_user_trace import (
    extract_ask_user_clarification_blocks,
    extract_ask_user_clarifications,
)
from .model_history import (
    SUMMARY_SNAPSHOT_NAME,
    history_groups,
    model_turn,
    replay_history,
    summary_snapshot,
)
from .protocol import SessionStoreProtocol
from .provider_response_state import normalize_provider_response_state

logger = logging.getLogger(__name__)

#: When the summarizer's output lands within this fraction of its hard token
#: cap, assume the provider cut it mid-sentence and trim the partial tail.
TRUNCATION_GUARD_RATIO = 0.95

# Ratio-only budgets become impractical for models with very large context
# windows: a 1M-token window would otherwise reserve hundreds of thousands of
# tokens for chat history and ask the summarizer for a six-figure response.
# Keep the rolling-summary strategy, but bound its history plan, summary
# output, and raw-rebuild eligibility threshold. The summary ceiling is also
# constrained by the active generation limit when that setting is lower.
MAX_HISTORY_PLAN_TOKENS = 131_072
MAX_SUMMARY_OUTPUT_TOKENS = 16_384
MAX_RAW_REBUILD_TOKENS = 131_072

logger = logging.getLogger(__name__)


# Planning allowance per image, not provider-reported usage. Counting encoded
# image bytes as text can exhaust the entire history budget on one screenshot.
# Reserve nonzero headroom for vision while keeping it independent of PNG/JPEG
# compression and URL length. Apply request projection before counting so only
# images retained in the request consume this allowance; references remain text.
IMAGE_CONTEXT_TOKEN_ESTIMATE = 4096


# The summarizer's scratchpad has to be removed defensively: a custom
# OpenAI-compatible route can emit the model's reasoning inline instead of on a
# separate reasoning channel, and the observed output *began* with the drafting
# monologue under an unclosed tag. ``clean_thinking_tags`` removes an unclosed
# block through end of text, which here would have discarded the entire
# summary, so the tag is only trusted when it is closed.
_CLOSED_THINK_RE = re.compile(
    r"<\s*think(?:ing)?\b[^>]*>.*?<\s*/\s*think(?:ing)?\s*>", re.DOTALL | re.IGNORECASE
)
_OPEN_THINK_RE = re.compile(r"^<\s*think(?:ing)?\b[^>]*>", re.IGNORECASE | re.DOTALL)
_SUMMARY_SECTION_RE = re.compile(r"(?m)^[ \t]{0,3}#{1,6}[ \t]")
_MIN_SALVAGED_CHARS = 200


def sanitize_summary(text: str) -> str:
    """Drop a leaked reasoning scratchpad without ever losing the summary.

    A summary is replayed on every later turn until the next compaction, so
    scratchpad that leaks into it is paid for on every request — and, because
    the scratchpad is written first, it also eats the summarizer's generation
    budget and truncates the real content.
    """
    raw = (text or "").strip()
    if not raw:
        return ""
    cleaned = _CLOSED_THINK_RE.sub("", raw).strip()
    match = _OPEN_THINK_RE.match(cleaned)
    if match is None:
        return cleaned
    body = cleaned[match.end() :]
    # The tag was never closed: cut at the first heading the summarizer was
    # told to emit, and accept the cut only when a real body survives it.
    section = _SUMMARY_SECTION_RE.search(body)
    if section is not None and len(body) - section.start() >= _MIN_SALVAGED_CHARS:
        return body[section.start() :].strip()
    # Unstructured output: drop the marker itself rather than the content.
    return _OPEN_THINK_RE.sub("", cleaned).replace("</think>", "").strip() or raw


def count_tokens(text: str) -> int:
    """Estimate token count with tiktoken when available."""
    if not text:
        return 0
    try:
        import tiktoken

        encoding = tiktoken.get_encoding("cl100k_base")
        return len(encoding.encode(text))
    except Exception:
        return max(1, len(text) // 4)


def _count_model_context_tokens(value: Any) -> int:
    """Measure a temporary accounting view; never alter the replay payload.

    Keep all text, tool arguments/results and provider replay state in the
    existing serialized-text estimate. Only recognized multimodal image blocks
    use a separate allowance; their encoded bytes/URLs are not language tokens.
    This is a context-planning heuristic, not an exact vision billing counter.
    """
    image_count = 0

    def accounting_view(item: Any) -> Any:
        nonlocal image_count
        if isinstance(item, dict):
            kind = item.get("type")
            is_image = (
                (kind == "image_url" and "image_url" in item)
                or (kind == "input_image" and ("image_url" in item or "file_id" in item))
                or (kind == "image" and "source" in item)
            )
            if is_image:
                image_count += 1
                return {"type": "image"}
            return {key: accounting_view(child) for key, child in item.items()}
        if isinstance(item, list):
            return [accounting_view(child) for child in item]
        return item

    serialized = json.dumps(accounting_view(value), ensure_ascii=False)
    return count_tokens(serialized) + image_count * IMAGE_CONTEXT_TOKEN_ESTIMATE


def _count_projected_model_tokens(replay: list[dict[str, Any]]) -> int:
    projected_tokens = _count_model_context_tokens(deduplicate_user_images(replay))
    if logger.isEnabledFor(logging.DEBUG):
        logger.debug(
            "History budget: raw_replay_tokens=%d projected_replay_tokens=%d",
            _count_model_context_tokens(replay),
            projected_tokens,
        )
    return projected_tokens


def trim_incomplete_tail(text: str) -> str:
    """Drop the trailing partial line from output that hit a hard token cap.

    A summary cut mid-sentence would otherwise be persisted as-is; losing the
    last line is cheaper than carrying a corrupted entry forward.
    """
    lines = text.rstrip().split("\n")
    if len(lines) > 1:
        return "\n".join(lines[:-1]).rstrip()
    return text.rstrip()


def expand_message_context(message: dict[str, Any]) -> list[dict[str, Any]]:
    """Expand one stored row into its true assistant/user chronology."""
    role = str(message.get("role", "user"))
    content = str(message.get("content", "") or "")
    blocks = extract_ask_user_clarification_blocks(message)
    if role != "assistant" or not blocks:
        return [{"role": role, "content": content}] if content.strip() else []

    expanded: list[dict[str, str]] = []
    cursor = 0
    for raw_offset, clarification in blocks:
        offset = min(len(content), max(cursor, raw_offset))
        prefix = content[cursor:offset]
        if prefix.strip():
            expanded.append({"role": "assistant", "content": prefix})
        expanded.append({"role": "user", "content": clarification})
        cursor = offset
    suffix = content[cursor:]
    if suffix.strip():
        expanded.append({"role": "assistant", "content": suffix})
    return expanded


def format_messages_as_transcript(messages: list[dict[str, Any]]) -> str:
    lines: list[str] = []
    role_map = {
        "user": "User",
        "assistant": "Assistant",
        "system": "System",
    }
    for item in messages:
        for expanded in expand_message_context(item):
            content = expanded["content"].strip()
            role = role_map.get(expanded["role"], "User")
            lines.append(f"{role}: {content}")
    return "\n\n".join(lines)


def build_history_text(history: list[dict[str, Any]]) -> str:
    lines: list[str] = []
    for item in history:
        role = str(item.get("role", "user"))
        content = str(item.get("content", "") or "").strip()
        if not content:
            continue
        if role == "system":
            lines.append(f"Conversation summary:\n{content}")
        elif role == "assistant":
            lines.append(f"Assistant: {content}")
        else:
            lines.append(f"User: {content}")
    return "\n\n".join(lines)


def _provider_response_state_tokens(message: dict[str, Any]) -> int:
    metadata = message.get("metadata")
    state = normalize_provider_response_state(
        metadata.get("provider_response_state") if isinstance(metadata, dict) else None
    )
    if state is None:
        return 0
    try:
        serialized = json.dumps(state, ensure_ascii=False, separators=(",", ":"))
    except (TypeError, ValueError):
        serialized = str(state)
    return count_tokens(serialized)


@dataclass
class ContextBuildResult:
    conversation_history: list[dict[str, Any]]
    conversation_summary: str
    context_text: str
    events: list[StreamEvent]
    token_count: int
    budget: int
    model_history: list[dict[str, Any]] | None = None
    previous_model_turn: dict[str, Any] | None = None
    history_sources: dict[str, str] = field(default_factory=dict)


class _ContextSummaryAgent(BaseAgent):
    """Small helper agent for compressing older conversation turns."""

    def __init__(self, language: str = "en") -> None:
        super().__init__(
            module_name="chat",
            agent_name="context_summary_agent",
            language=language,
        )

    async def process(self, *_args, **_kwargs) -> dict[str, Any]:
        raise NotImplementedError


class ContextBuilder:
    """Construct history against a bounded plan plus optional summary trace.

    The budget is a planning target, not destructive truncation: the newest
    non-empty message is retained even when that single message exceeds it.
    """

    def __init__(
        self,
        store: SessionStoreProtocol,
        history_budget_ratio: float = 0.35,
        summary_target_ratio: float = 0.40,
    ) -> None:
        self.store = store
        self.history_budget_ratio = history_budget_ratio
        self.summary_target_ratio = summary_target_ratio

    def _effective_context_window(self, llm_config: LLMConfig) -> int:
        return resolve_effective_context_window(
            context_window=getattr(llm_config, "context_window", None),
            model=str(getattr(llm_config, "model", "") or ""),
            max_tokens=getattr(llm_config, "max_tokens", None),
        )

    def _history_budget(self, llm_config: LLMConfig) -> int:
        effective_context_window = self._effective_context_window(llm_config)
        ratio_budget = max(256, int(effective_context_window * self.history_budget_ratio))
        return min(ratio_budget, MAX_HISTORY_PLAN_TOKENS)

    def _summary_budget(self, budget: int, llm_config: LLMConfig | None = None) -> int:
        ratio_budget = max(96, int(budget * self.summary_target_ratio))
        output_cap = MAX_SUMMARY_OUTPUT_TOKENS
        if llm_config is not None:
            generation_limit = coerce_positive_int(getattr(llm_config, "max_tokens", None))
            if generation_limit is not None:
                output_cap = min(output_cap, generation_limit)
        return min(ratio_budget, output_cap)

    def _recent_budget(self, budget: int) -> int:
        # Keep the original ratio-based split independent of the summarizer's
        # output cap. Otherwise lowering that cap expands the verbatim tail and
        # leaves almost no headroom before the next compaction.
        return max(128, int(budget * (1 - self.summary_target_ratio)))

    def _rebuild_source_budget(self, llm_config: LLMConfig) -> int:
        # A raw prefix is eligible for drift-free rebuild up to this threshold;
        # beyond it we degrade to fold-in (existing summary + new turns).
        ratio_budget = max(1024, self._effective_context_window(llm_config) // 2)
        return min(ratio_budget, MAX_RAW_REBUILD_TOKENS)

    def _build_history(self, summary: str, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
        history: list[dict[str, Any]] = []
        cleaned_summary = summary.strip()
        if cleaned_summary:
            history.append({"role": "system", "content": cleaned_summary})
        for item in messages:
            expanded_start = len(history)
            for expanded in expand_message_context(item):
                if expanded["role"] in {"user", "assistant"}:
                    history.append(expanded)
            if item.get("role") != "assistant":
                continue
            metadata = item.get("metadata")
            provider_state = normalize_provider_response_state(
                metadata.get("provider_response_state") if isinstance(metadata, dict) else None
            )
            if provider_state is None:
                continue
            for expanded in reversed(history[expanded_start:]):
                if expanded.get("role") == "assistant" and expanded.get("content"):
                    expanded["_provider_response_state"] = provider_state
                    break
        return history

    async def _append_event(
        self,
        events: list[StreamEvent],
        event: StreamEvent,
        on_event: Callable[[StreamEvent], Awaitable[None]] | None = None,
    ) -> None:
        events.append(event)
        if on_event is not None:
            await on_event(event)

    def _select_recent_messages(
        self,
        messages: list[dict[str, Any]],
        recent_budget: int,
        route: dict[str, str] | None = None,
    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
        groups = history_groups(messages)
        if any(model_turn(row) is not None for row in messages):
            # Rebuild each group once, then find the longest fitting suffix.
            # Images are shared across turns: adding per-group costs overcounts
            # repeats, while replaying every growing tail is quadratic work.
            replay_groups = [replay_history(group, route=route) for group in groups]
            start, end = 0, len(groups) - 1
            while start < end:
                middle = (start + end) // 2
                candidate = [message for group in replay_groups[middle:] for message in group]
                if _count_projected_model_tokens(candidate) <= recent_budget:
                    end = middle
                else:
                    start = middle + 1
            # Always retain the newest whole turn, even if it alone overflows.
            cutoff = sum(len(group) for group in groups[:start])
            return messages[:cutoff], messages[cutoff:]

        selected: list[dict[str, Any]] = []
        total = 0
        for group in reversed(groups):
            tokens = 0
            for item in group:
                content = str(item.get("content", "") or "")
                clarification = extract_ask_user_clarifications(item)
                tokens += count_tokens(f"{content}\n{clarification}" if clarification else content)
                tokens += _provider_response_state_tokens(item)
            if selected and total + tokens > recent_budget:
                break
            selected[0:0] = group
            total += tokens
        cutoff = len(messages) - len(selected)
        return messages[:cutoff], selected

    def _model_tokens(
        self,
        messages: list[dict[str, Any]],
        summary: str = "",
        route: dict[str, str] | None = None,
    ) -> int:
        if any(model_turn(row) is not None for row in messages):
            replayed = replay_history(messages, route=route)
            tokens = _count_projected_model_tokens(replayed)
            # The answer loop appends the summary as a trailing snapshot, but
            # only when it differs from the revision already replayed with the
            # history. Count what the request will actually carry.
            pending = summary_snapshot(summary)
            if pending is not None and not any(
                item.get("_context_snapshot") == SUMMARY_SNAPSHOT_NAME
                and item.get("content") == pending["content"]
                for item in replayed
            ):
                tokens += _count_model_context_tokens(pending)
            return tokens
        return count_tokens(build_history_text(self._build_history(summary, messages))) + sum(
            _provider_response_state_tokens(row) for row in messages
        )

    async def _summarize(
        self,
        *,
        session_id: str,
        language: str,
        source_text: str,
        summary_budget: int,
        generation_budget: int | None = None,
        on_event: Callable[[StreamEvent], Awaitable[None]] | None = None,
        replay_request: dict[str, Any] | None = None,
    ) -> tuple[str, list[StreamEvent]]:
        events: list[StreamEvent] = []
        if not source_text.strip():
            return "", events

        agent = _ContextSummaryAgent(language=language)
        trace_meta = build_trace_metadata(
            call_id=new_call_id("context-summary"),
            phase="summarize_context",
            label="Summarize context",
            call_kind="llm_summarization",
            trace_id=session_id,
        )

        async def _trace_bridge(update: dict[str, Any]) -> None:
            if str(update.get("event", "")) != "llm_call":
                return
            state = str(update.get("state", "running"))
            metadata = {
                key: value
                for key, value in update.items()
                if key not in {"event", "state", "response", "chunk"}
            }
            if state == "running":
                await self._append_event(
                    events,
                    StreamEvent(
                        type=StreamEventType.PROGRESS,
                        source="context_builder",
                        stage="summarize_context",
                        content="Compressing conversation history...",
                        metadata=merge_trace_metadata(
                            metadata,
                            {"trace_kind": "call_status", "call_state": "running"},
                        ),
                    ),
                    on_event,
                )
            elif state == "complete":
                response = str(update.get("response", "") or "")
                if response:
                    await self._append_event(
                        events,
                        StreamEvent(
                            type=StreamEventType.CONTENT,
                            source="context_builder",
                            stage="summarize_context",
                            content=response,
                            metadata=merge_trace_metadata(
                                metadata,
                                {"trace_kind": "llm_output"},
                            ),
                        ),
                        on_event,
                    )
                await self._append_event(
                    events,
                    StreamEvent(
                        type=StreamEventType.PROGRESS,
                        source="context_builder",
                        stage="summarize_context",
                        content="",
                        metadata=merge_trace_metadata(
                            metadata,
                            {"trace_kind": "call_status", "call_state": "complete"},
                        ),
                    ),
                    on_event,
                )
            elif state == "error":
                await self._append_event(
                    events,
                    StreamEvent(
                        type=StreamEventType.ERROR,
                        source="context_builder",
                        stage="summarize_context",
                        content=str(update.get("response", "") or "Context summarization failed."),
                        metadata=merge_trace_metadata(metadata, {"call_state": "error"}),
                    ),
                    on_event,
                )

        agent.set_trace_callback(_trace_bridge)
        await self._append_event(
            events,
            StreamEvent(
                type=StreamEventType.STAGE_START,
                source="context_builder",
                stage="summarize_context",
                metadata=trace_meta,
            ),
            on_event,
        )
        # The instruction targets ~80% of the hard cap so the model's own
        # length control — not the max_tokens cut — is the binding limit.
        target_tokens = max(1, int(summary_budget * 0.8))
        # The summary is replayed as a system row on every later turn, so the
        # language it is written in keeps steering the answer long after the
        # turns it condensed have scrolled out. Unstated, a summary of a
        # foreign-language session comes back in the default language and the
        # reply follows it — #1511's drift "after a few rounds".
        system_prompt = self._summary_instruction(language)
        user_prompt = (
            f"Update the summary using the material below. "
            f"Keep the total under {target_tokens} tokens.\n\n{source_text}"
        )
        if language.startswith("zh"):
            user_prompt = (
                f"请基于下面的材料更新摘要,总长度不超过 {target_tokens} tokens。\n\n{source_text}"
            )
        try:
            _chunks: list[str] = []
            outcome = StreamOutcome()
            replay_kwargs: dict[str, Any] = {}
            if replay_request is not None:
                # Reuse the conversation's warm prefix; only the instruction
                # is new. Tools are present for cache identity, never executed.
                instruction = (
                    f"{system_prompt}\n\nSummarize the conversation above in at most "
                    f"{target_tokens} tokens. Output only the summary; do not call tools."
                )
                replay_kwargs = {
                    "messages": deduplicate_user_images(
                        [
                            *replay_request["messages"],
                            {"role": "user", "content": instruction},
                        ]
                    ),
                    "tools": replay_request.get("tools"),
                }
            async for _c in agent.stream_llm(
                user_prompt=user_prompt,
                system_prompt=system_prompt,
                max_tokens=generation_budget or summary_budget,
                stage="summarize_context",
                trace_meta=trace_meta,
                outcome=outcome,
                **replay_kwargs,
            ):
                _chunks.append(_c)
            summary = sanitize_summary("".join(_chunks))
            return self._finalize_summary(summary, summary_budget, outcome), events
        finally:
            await self._append_event(
                events,
                StreamEvent(
                    type=StreamEventType.STAGE_END,
                    source="context_builder",
                    stage="summarize_context",
                    metadata=trace_meta,
                ),
                on_event,
            )

    def _finalize_summary(self, summary: str, summary_budget: int, outcome: StreamOutcome) -> str:
        """Legacy prose summaries can trim a partial final sentence."""
        if count_tokens(summary) >= int(summary_budget * TRUNCATION_GUARD_RATIO):
            return trim_incomplete_tail(summary)
        return summary

    def _summary_instruction(self, language: str) -> str:
        """The summary task's policy, independently of a tutor's large prompt."""
        summary_language = language_label(language)
        system_prompt = (
            "You maintain a running summary of a conversation so future turns can "
            "continue seamlessly. Rewrite the summary from the material provided, "
            "organized under these headings (omit any heading with no content):\n"
            "- Goals: what the user wants to accomplish, and why if stated\n"
            "- Key facts & context: stable facts, definitions, data points, names, "
            "references (files, links, IDs)\n"
            "- Decisions & preferences: choices made, options rejected, style or "
            "format preferences, capability/mode switches\n"
            "- Progress: what has been produced or completed so far\n"
            "- Open items: unanswered questions, pending tasks, known blockers\n"
            "Carry forward still-relevant entries from the existing summary unchanged "
            "unless new information contradicts them; drop only what is obsolete. "
            "Prefer concrete details (numbers, identifiers, exact terms) over "
            "abstract restatement. Never invent information. "
            "Output the summary body only: no preamble, no drafting notes, no "
            "step-by-step reasoning, and no <think> blocks — start directly at "
            "the first heading. "
            f"Write the summary itself in {summary_language}."
        )
        if language.startswith("zh"):
            system_prompt = (
                "你负责维护一份对话的滚动摘要,供后续轮次无缝衔接。请基于给定材料重写摘要,"
                "按以下小节组织(无内容的小节直接省略):\n"
                "- 目标:用户想完成什么,以及(如有说明)原因\n"
                "- 关键事实与上下文:稳定的事实、定义、数据、名称、引用(文件、链接、ID)\n"
                "- 决定与偏好:已做的选择、被否决的方案、风格/格式偏好、能力或模式切换\n"
                "- 进展:目前已经产出或完成的内容\n"
                "- 待办事项:未回答的问题、未完成的任务、已知阻塞\n"
                "已有摘要中仍然有效的条目应原样保留,仅在新信息与之矛盾时修改,只删除确已过时"
                "的内容。优先保留具体细节(数字、标识符、确切措辞),不要抽象转述,绝不虚构。"
                "只输出摘要正文:不要输出任何思考过程或 <think> 标记,不要写草稿、不要写"
                "「Let me…」「Draft:」之类的推演,直接从第一个小节标题开始。"
                f"摘要正文本身请使用{summary_language}撰写。"
            )
        return system_prompt

    async def build(
        self,
        *,
        session_id: str,
        llm_config: LLMConfig,
        language: str = "en",
        on_event: Callable[[StreamEvent], Awaitable[None]] | None = None,
        leaf_message_id: int | None = None,
    ) -> ContextBuildResult:
        session = await self.store.get_session(session_id)
        # When ``leaf_message_id`` is given (edit-branch turn), only the
        # ancestor path of that message is included in context — sibling
        # branches at any depth are excluded.
        messages = await self.store.get_messages_for_context(
            session_id, leaf_message_id=leaf_message_id
        )
        if session is None:
            return ContextBuildResult([], "", "", [], 0, self._history_budget(llm_config))

        budget = self._history_budget(llm_config)
        summary_budget = self._summary_budget(budget, llm_config)
        recent_budget = self._recent_budget(budget)

        stored_summary = str(session.get("compressed_summary", "") or "").strip()
        summary_up_to_msg_id = session.get("summary_up_to_msg_id", 0) or 0
        # Branch guard: the watermark must sit on this turn's ancestor chain.
        # After an edit-branch switch it may point into a sibling branch — the
        # stored summary would then carry content this branch never saw.
        # Discard both and rebuild from this branch's own messages.
        summary_position = next(
            (
                index
                for index, item in enumerate(messages)
                if summary_up_to_msg_id and str(item.get("id")) == str(summary_up_to_msg_id)
            ),
            None,
        )
        if summary_up_to_msg_id and summary_position is None:
            stored_summary = ""
            summary_up_to_msg_id = 0
        unsummarized = (
            messages[summary_position + 1 :] if summary_position is not None else messages
        )

        binding = getattr(llm_config, "binding", None)
        route = (
            {"provider": binding, "model": llm_config.model} if isinstance(binding, str) else None
        )
        if os.getenv("DEEPTUTOR_CHAT_ENGINE") == "typescript-native":
            from deeptutor.runtime.ts_engine.config import compatibility_reason

            if not compatibility_reason(llm_config):
                from .native_history import build_native_history

                return await build_native_history(
                    self,
                    session_id=session_id,
                    llm_config=llm_config,
                    language=language,
                    messages=messages,
                    unsummarized=unsummarized,
                    summary=stored_summary,
                    route=route,
                    on_event=on_event,
                )
        current_history = self._build_history(stored_summary, unsummarized)
        current_tokens = self._model_tokens(unsummarized, stored_summary, route)
        previous_model_turn = next(
            (record for row in reversed(messages) if (record := model_turn(row)) is not None),
            None,
        )
        if current_tokens <= budget:
            return ContextBuildResult(
                conversation_history=current_history,
                conversation_summary=stored_summary,
                context_text=build_history_text(current_history),
                events=[],
                token_count=current_tokens,
                budget=budget,
                model_history=replay_history(unsummarized, stored_summary, route),
                previous_model_turn=previous_model_turn,
            )

        older_unsummarized, recent_messages = self._select_recent_messages(
            unsummarized, recent_budget, route=route
        )
        # Everything not retained verbatim: previously summarized messages
        # plus the older unsummarized turns.
        prefix_messages = messages[: len(messages) - len(recent_messages)]
        prefix_transcript = format_messages_as_transcript(prefix_messages)

        # Anti-drift: while the raw prefix still fits the rebuild budget,
        # re-summarize from the original messages instead of folding the
        # previous summary into itself — summary-of-summary loses detail
        # monotonically. Only beyond that budget degrade to fold-in.
        rebuild_from_raw = bool(prefix_transcript) and count_tokens(
            prefix_transcript
        ) <= self._rebuild_source_budget(llm_config)
        merge_parts: list[str] = []
        if rebuild_from_raw:
            merge_parts.append(f"Conversation history to summarize:\n{prefix_transcript}")
        else:
            if stored_summary:
                merge_parts.append(f"Existing summary:\n{stored_summary}")
            older_transcript = format_messages_as_transcript(older_unsummarized)
            if older_transcript:
                merge_parts.append(f"Older turns to fold in:\n{older_transcript}")
        if not merge_parts and recent_messages:
            merge_parts.append(format_messages_as_transcript(recent_messages))

        summarize_ok = True
        replay_request = None
        if (
            previous_model_turn
            and older_unsummarized
            and isinstance(previous_model_turn.get("system"), str)
        ):
            # The current retained prefix is authoritative once model turns
            # exist; legacy sessions keep their raw-transcript rebuild path.
            replay_request = {
                "messages": [
                    {"role": "system", "content": previous_model_turn["system"]},
                    *[
                        {key: value for key, value in message.items() if key != "_context_snapshot"}
                        for message in replay_history(older_unsummarized, stored_summary, route)
                    ],
                ],
                "tools": previous_model_turn.get("tools"),
                "rows": older_unsummarized,
            }
            pending_summary = summary_snapshot(stored_summary)
            if pending_summary is not None and not any(
                message.get("content") == pending_summary["content"]
                for message in replay_request["messages"]
            ):
                replay_request["messages"].append(
                    {
                        key: value
                        for key, value in pending_summary.items()
                        if key != "_context_snapshot"
                    }
                )
        try:
            self._summary_rows = older_unsummarized
            self._summary_prior = stored_summary
            summary_kwargs: dict[str, Any] = (
                {"replay_request": replay_request} if replay_request else {}
            )
            new_summary, events = await self._summarize(
                session_id=session_id,
                language=language,
                source_text="\n\n".join(part for part in merge_parts if part.strip()),
                summary_budget=summary_budget,
                on_event=on_event,
                **summary_kwargs,
            )
        except Exception as exc:
            summarize_ok = False
            new_summary = ""
            events = []
            # Keep private transcript/provider details out of diagnostics.
            logger.warning(
                "Context condensation failed (%s); bounding recent history without advancing its watermark",
                type(exc).__name__,
            )

        if summarize_ok and new_summary:
            # Advance the watermark only on a successful summarize — never
            # past turns that were not actually folded in.
            up_to_msg_id = summary_up_to_msg_id
            if prefix_messages:
                up_to_msg_id = prefix_messages[-1].get("id", 0) or 0
            await self.store.update_summary(session_id, new_summary, up_to_msg_id)
            stored_summary = new_summary
            retained_rows = recent_messages
        else:
            # Degrade for this turn only: keep the stale summary and as many
            # unsummarized turns as fit; nothing is marked as summarized, so
            # the next turn retries with the full material.
            retained_rows = unsummarized
        retained_groups = history_groups(retained_rows)
        while (
            len(retained_groups) > 1
            and self._model_tokens(retained_rows, stored_summary, route) > budget
        ):
            retained_groups.pop(0)
            retained_rows = [row for group in retained_groups for row in group]
        final_history = self._build_history(stored_summary, retained_rows)

        final_text = build_history_text(final_history)
        return ContextBuildResult(
            conversation_history=final_history,
            conversation_summary=stored_summary,
            context_text=final_text,
            events=events,
            token_count=self._model_tokens(retained_rows, stored_summary, route),
            budget=budget,
            model_history=replay_history(retained_rows, stored_summary, route),
            previous_model_turn=previous_model_turn,
        )


__all__ = [
    "ContextBuildResult",
    "ContextBuilder",
    "TRUNCATION_GUARD_RATIO",
    "build_history_text",
    "count_tokens",
    "format_messages_as_transcript",
    "extract_ask_user_clarifications",
    "trim_incomplete_tail",
]