iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/context/compaction/exclusions.py

@@ -0,0 +1,261 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Weak exclusion anchors for compaction state propagation."""
+
+from __future__ import annotations
+
+import weakref
+from copy import copy
+from dataclasses import dataclass
+
+from chrys.foundation.trajectory.metadata import read_analytics_item_id
+from chrys.kernel import (
+    EXCLUDE_REASON_KEY,
+    EXCLUDED_KEY,
+    GROUP_ANNOTATION_KEY,
+    GROUP_ID_KEY,
+    SUMMARIZED_BY_SUMMARY_ID_KEY,
+    SUMMARY_OF_GROUP_IDS_KEY,
+    Content,
+    Message,
+    set_excluded,
+)
+from chrys.kernel.identity import ContentList
+
+from .events import _COMPACTION_EXCLUDE_REASONS, _REASON_COMPRESSION, CachedSummary
+from .groups import _content_signature, _message_call_ids
+from .summaries import _set_summarized
+
+
+@dataclass(frozen=True)
+class _ExclusionAnchor:
+    """Persist a tool-loop exclusion onto the matching state message.
+
+    Per-call wire views can copy a Message's contents list, so contents-list
+    identity alone cannot locate every anchor in the stored messages.
+    Structural fallback is intentionally limited to role + call_ids, and scans
+    from the end so current-turn tool calls win over older reused call ids.
+
+    Identity tiers hold WEAK references. Anchors may survive an interrupted
+    run whose ``after_run`` never fired; a weak tier lives exactly as long
+    as its object, so a collected list or content simply stops matching —
+    a recycled address can never false-match, and the anchor never keeps
+    its source alive.
+    """
+
+    reason: str | None
+    role: str
+    contents_ref: weakref.ref[ContentList] | None
+    call_ids: tuple[str, ...] = ()
+    content_signature: tuple[tuple[str, str | None, str | None, str], ...] = ()
+    message_id: str | None = None
+    content_refs: tuple[weakref.ref[Content], ...] = ()
+    summary_id: str | None = None
+
+    @classmethod
+    def from_message(cls, msg: Message) -> _ExclusionAnchor:
+        annotation = msg.additional_properties.get(GROUP_ANNOTATION_KEY)
+        summary_id = annotation.get(SUMMARIZED_BY_SUMMARY_ID_KEY) if isinstance(annotation, dict) else None
+        return cls(
+            reason=msg.additional_properties.get(EXCLUDE_REASON_KEY),
+            role=msg.role,
+            contents_ref=weakref.ref(msg.contents),
+            call_ids=_message_call_ids(msg),
+            content_signature=_content_signature(msg),
+            message_id=msg.message_id,
+            content_refs=tuple(weakref.ref(c) for c in msg.contents),
+            summary_id=summary_id if isinstance(summary_id, str) else None,
+        )
+
+    def find_in(self, messages: list[Message], used_indices: set[int]) -> int | None:
+        snapshot = self.contents_ref() if self.contents_ref is not None else None
+        if snapshot is not None:
+            for i, msg in enumerate(messages):
+                if i not in used_indices and msg.contents is snapshot and self._matches_shape(msg):
+                    return i
+        # The wire hands clients per-call views: fresh wrapper + fresh
+        # contents LIST, but the content OBJECTS are shared with the state
+        # original — matching on their identity keeps identity-level
+        # precision for anchors snapshotted from a view. A dead ref matches
+        # nothing: ``ref() is c`` cannot hold for a live content.
+        if self.content_refs:
+            for i, msg in enumerate(messages):
+                if (
+                    i not in used_indices
+                    and len(msg.contents) == len(self.content_refs)
+                    and all(ref() is c for ref, c in zip(self.content_refs, msg.contents, strict=True))
+                    and self._matches_shape(msg)
+                ):
+                    return i
+        if self.message_id:
+            for i, msg in enumerate(messages):
+                if i not in used_indices and msg.message_id == self.message_id and self._matches_shape(msg):
+                    return i
+        if self.content_signature or self.call_ids:
+            for i in range(len(messages) - 1, -1, -1):
+                if i in used_indices:
+                    continue
+                msg = messages[i]
+                if self._matches_shape(msg):
+                    return i
+        return None
+
+    def _matches_shape(self, msg: Message) -> bool:
+        """Return whether *msg* matches the stable structural anchor keys."""
+        if msg.role != self.role:
+            return False
+        if self.call_ids and _message_call_ids(msg) != self.call_ids:
+            return False
+        return not self.content_signature or _content_signature(msg) == self.content_signature
+
+
+class ExclusionLedger:
+    """Own compaction caches and weak exclusion anchors."""
+
+    def __init__(self) -> None:
+        self._summary_cache: dict[str, CachedSummary] = {}
+        self._removed_group_ids: set[str] = set()
+        self._excluded_anchors: list[_ExclusionAnchor] = []
+
+    def reset_stale_exclusions(self, messages: list[Message]) -> None:
+        """Reset stale foreign exclusions while retaining owned state."""
+        if self._summary_cache or self._removed_group_ids:
+            self.reinject_cached_summaries(messages)
+            # Reset _excluded only for messages NOT managed by our compaction
+            for msg in messages:
+                if not msg.additional_properties.get(EXCLUDED_KEY, False):
+                    continue
+                annotation = msg.additional_properties.get(GROUP_ANNOTATION_KEY)
+                if isinstance(annotation, dict):
+                    if SUMMARIZED_BY_SUMMARY_ID_KEY in annotation:
+                        continue  # Keep excluded — our cached summary replaces it
+                    # Keep excluded if the group was fully removed (Phase 2/3)
+                    gid = annotation.get(GROUP_ID_KEY)
+                    if gid and gid in self._removed_group_ids:
+                        continue
+                    # Keep excluded if it's a summary of a removed group
+                    summary_of = annotation.get(SUMMARY_OF_GROUP_IDS_KEY)
+                    if summary_of and any(g in self._removed_group_ids for g in summary_of):
+                        continue
+                # Preserve exclusions from prior-session compaction that
+                # this strategy instance doesn't track in its caches.
+                reason = msg.additional_properties.get(EXCLUDE_REASON_KEY)
+                if reason in _COMPACTION_EXCLUDE_REASONS:
+                    continue
+                msg.additional_properties[EXCLUDED_KEY] = False
+        else:
+            for msg in messages:
+                if msg.additional_properties.get(EXCLUDED_KEY, False):
+                    # Preserve exclusions set by compaction in a prior
+                    # session — the _exclude_reason annotation survives
+                    # serialization and identifies legitimate compaction
+                    # flags even when the strategy has no cache.
+                    reason = msg.additional_properties.get(EXCLUDE_REASON_KEY)
+                    if reason in _COMPACTION_EXCLUDE_REASONS:
+                        continue
+                    msg.additional_properties[EXCLUDED_KEY] = False
+
+    def persist_to_state(self, state_messages: list[Message]) -> None:
+        """Persist exclusions and their replacement summaries before history filters."""
+        used_indices: set[int] = set()
+        for anchor in self._excluded_anchors:
+            idx = anchor.find_in(state_messages, used_indices)
+            if idx is None:
+                continue
+            used_indices.add(idx)
+            set_excluded(state_messages[idx], excluded=True, reason=anchor.reason)
+            if anchor.summary_id is not None:
+                _set_summarized(state_messages[idx], anchor.summary_id)
+        self._excluded_anchors = []
+        self.reinject_cached_summaries(state_messages)
+
+    def snapshot_retry_state(self) -> tuple[_ExclusionAnchor, ...]:
+        """Capture the current consume-once anchor list."""
+        return tuple(self._excluded_anchors)
+
+    def restore_retry_state(self, anchors: tuple[_ExclusionAnchor, ...]) -> None:
+        """Restore anchors captured at retry-attempt entry."""
+        self._excluded_anchors = list(anchors)
+
+    def snapshot_excluded_anchors(self, messages: list[Message]) -> None:
+        """Snapshot non-compression exclusions for after-run propagation."""
+        self._excluded_anchors = [
+            _ExclusionAnchor.from_message(msg)
+            for msg in messages
+            if msg.additional_properties.get(EXCLUDED_KEY, False)
+            and msg.additional_properties.get(EXCLUDE_REASON_KEY) != _REASON_COMPRESSION
+        ]
+
+    def invalidate_for_fold(self, fold_range: list[Message]) -> None:
+        """Remove compaction cache entries for messages folded by compression.
+
+        When a cross-turn compression folds messages that were previously
+        compacted (Phase 1) or removed (Phase 2/3), the corresponding
+        ``_summary_cache`` and ``_removed_group_ids`` entries become stale.
+        """
+        for msg in fold_range:
+            # A fold may contain only a persisted summary: originals have
+            # already been filtered out of the provider's visible history.
+            item_id = read_analytics_item_id(msg.additional_properties)
+            if item_id is not None:
+                self._summary_cache.pop(f"tool_summary_{item_id}", None)
+            annotation = msg.additional_properties.get(GROUP_ANNOTATION_KEY)
+            if not isinstance(annotation, dict):
+                continue
+            summary_id = annotation.get(SUMMARIZED_BY_SUMMARY_ID_KEY)
+            if isinstance(summary_id, str):
+                self._summary_cache.pop(summary_id, None)
+            gid = annotation.get(GROUP_ID_KEY)
+            if gid:
+                self._removed_group_ids.discard(gid)
+
+    def reinject_cached_summaries(self, messages: list[Message]) -> None:
+        """Re-inject cached tool summaries missing from a replayed list.
+
+        This is normally unnecessary for the active tool loop because
+        compaction mutates the loop's list in place. It remains
+        useful for copied/replayed lists where excluded originals reference a
+        cached summary via ``SUMMARIZED_BY_SUMMARY_ID_KEY`` but the summary
+        message itself is absent.
+        """
+        if not self._summary_cache:
+            return
+
+        # Collect summary_ids referenced by messages in this list
+        present_ids = {read_analytics_item_id(msg.additional_properties) for msg in messages}
+        needed: dict[str, int] = {}
+
+        for i, msg in enumerate(messages):
+            annotation = msg.additional_properties.get(GROUP_ANNOTATION_KEY)
+            if not isinstance(annotation, dict):
+                continue
+            sid = annotation.get(SUMMARIZED_BY_SUMMARY_ID_KEY)
+            if (
+                isinstance(sid, str)
+                and sid in self._summary_cache
+                and self._summary_cache[sid].item_id not in present_ids
+                and sid not in needed
+            ):
+                needed[sid] = i
+
+        # Insert in reverse order to preserve indices
+        for sid in sorted(needed, key=lambda item: needed[item], reverse=True):
+            cached = self._summary_cache[sid]
+            # Keep wrapper/list ownership separate, but share content identity
+            # and metadata so later exclusions also reach the stored summary.
+            summary_msg = copy(cached.message)
+            summary_msg.contents = list(cached.message.contents)
+            messages.insert(needed[sid], summary_msg)
+
+    def discard_unreferenced_summaries(self, messages: list[Message]) -> None:
+        """Drop attempt-local summaries after history rollback removes their references."""
+        referenced: set[str] = set()
+        for message in messages:
+            item_id = read_analytics_item_id(message.additional_properties)
+            if item_id is not None:
+                referenced.add(f"tool_summary_{item_id}")
+            annotation = message.additional_properties.get(GROUP_ANNOTATION_KEY)
+            if isinstance(annotation, dict) and isinstance(sid := annotation.get(SUMMARIZED_BY_SUMMARY_ID_KEY), str):
+                referenced.add(sid)
+        for sid in self._summary_cache.keys() - referenced:
+            del self._summary_cache[sid]

chrys/service/context/compaction/groups.py

@@ -0,0 +1,361 @@
+# Copyright (c) Microsoft. All rights reserved.
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+# Contains code adapted from Microsoft Agent Framework (MIT License; see NOTICE).
+
+"""Message content signatures and compaction group walkers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from collections.abc import Iterable
+from typing import Any
+
+from chrys.foundation.text.images import hashable_image_identity
+from chrys.foundation.trajectory.metadata import read_analytics_item_id
+from chrys.kernel import (
+    EXCLUDED_KEY,
+    GROUP_ANNOTATION_KEY,
+    SUMMARIZED_BY_SUMMARY_ID_KEY,
+    SUMMARY_OF_GROUP_IDS_KEY,
+    Content,
+    Message,
+    is_image_content,
+)
+from chrys.kernel.compaction import _group_id, _group_kind
+from chrys.kernel.identity import WeakIdentityRegistry
+from chrys.service.context.tool_content import tool_call_name
+
+_log = logging.getLogger(__name__)
+
+
+def _tool_call_name(content: Content) -> str | None:
+    """Compatibility facade for compaction and recall consumers."""
+    return tool_call_name(content)
+
+
+def _message_call_ids(msg: Message) -> tuple[str, ...]:
+    """Return call ids carried by framework content items."""
+    return tuple(c.call_id for c in msg.contents if c.call_id)
+
+
+def _render_tool_result_value(value: Any) -> str:
+    """Render one result payload without leaking Content object reprs."""
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list | tuple):
+        return "\n".join(part for item in value if (part := _render_tool_result_value(item)))
+    if isinstance(value, Content):
+        if value.type == "text":
+            return value.text or ""
+        if value.type == "shell_command_output":
+            parts = []
+            if value.stdout:
+                parts.append(value.stdout)
+            if value.stderr:
+                parts.append(f"stderr: {value.stderr}")
+            if value.exit_code is not None:
+                parts.append(f"exit code: {value.exit_code}")
+            if value.timed_out:
+                parts.append("timed out")
+            return "\n".join(parts)
+        if value.type == "hosted_file":
+            return f"[file: {value.name or value.file_id or 'hosted file'}]"
+        if value.type == "hosted_vector_store":
+            return f"[vector store: {value.vector_store_id or 'hosted vector store'}]"
+        if value.type in {"data", "uri"}:
+            media_type = value.media_type or "binary"
+            if media_type.startswith("image/") or (value.uri or "").startswith("data:image/"):
+                return f"[{media_type} image]"
+            return f"[{media_type} artifact]"
+        return json.dumps(value.to_dict(exclude={"raw_representation"}), ensure_ascii=False, default=str)
+    if isinstance(value, dict):
+        return json.dumps(_without_inline_binary(value), ensure_ascii=False, sort_keys=True, default=str)
+    return str(value)
+
+
+def _without_inline_binary(value: Any) -> Any:
+    """Return *value* with inline base64 payloads replaced by a short placeholder.
+
+    Provider payloads kept as plain data (an Anthropic ``{"type": "base64"}``
+    source, such as a fetched PDF) would otherwise put their encoded bytes
+    into summaries.
+    """
+    if isinstance(value, dict):
+        if value.get("type") == "base64" and isinstance(value.get("data"), str):
+            return _inline_binary_placeholder(value.get("media_type"))
+        return {key: _without_inline_binary(item) for key, item in value.items()}
+    if isinstance(value, list | tuple):
+        return [_without_inline_binary(item) for item in value]
+    return value
+
+
+def _inline_binary_placeholder(media_type: object) -> str:
+    kind = media_type if isinstance(media_type, str) and media_type else "binary"
+    return f"[{kind} image]" if kind.startswith("image/") else f"[{kind} artifact]"
+
+
+def _tool_result_text(content: Content) -> str:
+    """Render live or restored local/hosted result payloads for summaries."""
+    if content.type == "function_result":
+        value = content.result if content.result is not None else content.items
+        return _render_tool_result_value(value)
+    if content.type in {"hosted_tool_result", "search_tool_result"}:
+        value = content.items or content.result
+        return _render_tool_result_value(value)
+    if content.type == "mcp_server_tool_result":
+        return _render_tool_result_value(content.output)
+    if content.type in {
+        "code_interpreter_tool_result",
+        "image_generation_tool_result",
+        "shell_tool_result",
+    }:
+        return _render_tool_result_value(content.outputs)
+    return ""
+
+
+def _content_signature(msg: Message) -> tuple[tuple[str, str | None, str | None, str], ...]:
+    """Return a stable, compact signature for message contents."""
+    parts: list[tuple[str, str | None, str | None, str]] = []
+    for content in msg.contents:
+        content_type = content.type
+        call_id = content.call_id or None
+        name = content.name or None
+        payload = _content_payload(content, content_type)
+        parts.append((content_type, call_id, name, _payload_digest(payload)))
+    return tuple(parts)
+
+
+def _content_payload(content: Any, content_type: str) -> Any:
+    if content_type == "function_call":
+        return getattr(content, "arguments", None)
+    if content_type == "function_result":
+        if isinstance(content, Content) and content.items:
+            image_payload = _function_result_image_payload(content)
+            if image_payload:
+                return {"result": content.result, "images": image_payload}
+        return getattr(content, "result", None)
+    if content_type == "text":
+        return getattr(content, "text", None)
+    if isinstance(content, str):
+        return content
+    to_dict = getattr(content, "to_dict", None)
+    if callable(to_dict):
+        return to_dict()
+    return repr(content)
+
+
+def _function_result_image_payload(content: Content) -> list[dict[str, Any]]:
+    images: list[dict[str, Any]] = []
+    if not content.items:
+        return images
+    for item in content.items:
+        if not is_image_content(item):
+            continue
+        byte_length, identity = hashable_image_identity(item.uri or "")
+        images.append(
+            {
+                "media_type": item.media_type,
+                "byte_length": byte_length,
+                "hash": hashlib.sha256(identity.encode("utf-8", errors="surrogatepass")).hexdigest()[:16],
+            }
+        )
+    return images
+
+
+def _payload_digest(payload: Any) -> str:
+    try:
+        data = json.dumps(payload, sort_keys=True, default=str, ensure_ascii=False)
+    except TypeError:
+        data = str(payload)
+    return hashlib.sha256(data.encode("utf-8", errors="surrogatepass")).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Group walkers over annotation metadata (chrys-owned data-structure tools;
+# the per-message accessors ``_group_id``/``_group_kind`` come from
+# ``chrys.kernel.compaction``)
+# ---------------------------------------------------------------------------
+
+
+def _ordered_group_ids(messages: list[Message]) -> list[str]:
+    ids: list[str] = []
+    seen: set[str] = set()
+    for msg in messages:
+        gid = _group_id(msg)
+        if gid is not None and gid not in seen:
+            seen.add(gid)
+            ids.append(gid)
+    return ids
+
+
+def _group_messages_by_id(messages: list[Message]) -> dict[str, list[Message]]:
+    grouped: dict[str, list[Message]] = {}
+    for msg in messages:
+        gid = _group_id(msg)
+        if gid is not None:
+            grouped.setdefault(gid, []).append(msg)
+    return grouped
+
+
+def _included_group_ids(messages: list[Message], ordered_ids: list[str]) -> list[str]:
+    grouped = _group_messages_by_id(messages)
+    return [
+        gid
+        for gid in ordered_ids
+        if any(not m.additional_properties.get(EXCLUDED_KEY, False) for m in grouped.get(gid, []))
+    ]
+
+
+def _group_start_indices(messages: list[Message]) -> dict[str, int]:
+    starts: dict[str, int] = {}
+    for idx, msg in enumerate(messages):
+        gid = _group_id(msg)
+        if gid is not None and gid not in starts:
+            starts[gid] = idx
+    return starts
+
+
+def _group_kind_map(messages: list[Message]) -> dict[str, str]:
+    kinds: dict[str, str] = {}
+    for msg in messages:
+        gid = _group_id(msg)
+        kind = _group_kind(msg)
+        if gid is not None and kind is not None and gid not in kinds:
+            kinds[gid] = kind
+    return kinds
+
+
+def _fold_summary_ids(messages: list[Message]) -> set[str]:
+    """Collect summary occurrences owned or referenced by a fold.
+
+    Positional group IDs can be reused in a later wire view. Only the stable
+    summary reference and analytics identity can associate its replacement
+    across copies. Legacy summaries without that identity still match through
+    the fold's shared content objects, never through their group labels.
+    """
+    summary_ids: set[str] = set()
+    for message in messages:
+        annotation = message.additional_properties.get(GROUP_ANNOTATION_KEY)
+        if not isinstance(annotation, dict):
+            continue
+        summary_id = annotation.get(SUMMARIZED_BY_SUMMARY_ID_KEY)
+        if isinstance(summary_id, str):
+            summary_ids.add(summary_id)
+        if isinstance(annotation.get(SUMMARY_OF_GROUP_IDS_KEY), list):
+            item_id = read_analytics_item_id(message.additional_properties)
+            if item_id is not None:
+                summary_ids.add(f"tool_summary_{item_id}")
+    return summary_ids
+
+
+def _matches_summary_id(message: Message, summary_ids: set[str] | frozenset[str]) -> bool:
+    """Match a replacement by occurrence, independently of its wire labels."""
+    item_id = read_analytics_item_id(message.additional_properties)
+    return item_id is not None and f"tool_summary_{item_id}" in summary_ids
+
+
+def _message_present(messages: list[Message], needle: Message) -> bool:
+    """Return whether *needle* is already represented in *messages*."""
+    if any(msg is needle for msg in messages):
+        return True
+    needle_block_id = needle.additional_properties.get("_block_id")
+    if needle_block_id is None:
+        return False
+    return any(msg.additional_properties.get("_block_id") == needle_block_id for msg in messages)
+
+
+def _content_object_ids(messages: Iterable[Message]) -> set[int]:
+    """Identity set of every content OBJECT carried by *messages*.
+
+    The stable cross-view currency: the kernel wire hands every layer
+    per-call message VIEWS — fresh wrapper + fresh contents list — so
+    wrapper identity and ``id(msg.contents)`` both break across the
+    state↔wire boundary, while the content objects stay shared. Bare-id
+    form for FRAME-LOCAL use only — a caller persisting identities across
+    calls builds a ``WeakIdentityRegistry`` instead, whose entries die
+    with their objects.
+    """
+    return {id(c) for m in messages for c in m.contents}
+
+
+def _carries_only(msg: Message, members: WeakIdentityRegistry | set[int] | frozenset[int]) -> bool:
+    """Whether *msg*'s contents are drawn entirely from *members*.
+
+    *members* is either a frame-local bare-id set or a persisted weak
+    registry (whose dead entries never match). Empty messages never match:
+    an empty contents list carries no identity evidence, and ``all()``
+    over it would vacuously claim membership.
+    """
+    if not msg.contents:
+        return False
+    if isinstance(members, WeakIdentityRegistry):
+        return all(c in members for c in msg.contents)
+    return all(id(c) in members for c in msg.contents)
+
+
+def _tool_groups_in_range(
+    start: int,
+    end: int,
+    ordered_ids: list[str],
+    kinds: dict[str, str],
+    starts: dict[str, int],
+    grouped: dict[str, list[Message]],
+) -> list[str]:
+    """Return included tool-call group IDs whose first message is in [start, end)."""
+    return [
+        gid
+        for gid in ordered_ids
+        if kinds.get(gid) == "tool_call"
+        and start <= starts.get(gid, -1) < end
+        and any(not m.additional_properties.get(EXCLUDED_KEY, False) for m in grouped.get(gid, []))
+    ]
+
+
+def _any_tool_groups_in_range(
+    start: int,
+    end: int,
+    ordered_ids: list[str],
+    kinds: dict[str, str],
+    starts: dict[str, int],
+) -> list[str]:
+    """Return ALL tool-call group IDs in [start, end), regardless of exclusion.
+
+    Used by Phase 2/3 which need to find groups that were already summarised
+    by Phase 1 (originals excluded, summary still visible).
+    """
+    return [gid for gid in ordered_ids if kinds.get(gid) == "tool_call" and start <= starts.get(gid, -1) < end]
+
+
+# ---------------------------------------------------------------------------
+# Message ID deduplication
+# ---------------------------------------------------------------------------
+
+
+def _dedup_message_ids(messages: list[Message]) -> None:
+    """Assign unique ``message_id`` values to messages with duplicate IDs.
+
+    Response aggregation can reuse sequential IDs (``msg_1``, ``msg_2``, …)
+    across runs within the same session. ``annotate_message_groups`` uses
+    ``message_id`` to form group IDs, so duplicates cause unrelated tool calls
+    from different turns to merge into a single mega-group, breaking
+    compaction completely.
+
+    This function detects duplicates and reassigns them with a positional
+    suffix (e.g. ``msg_2`` → ``msg_2_i42``) so each message gets its own
+    unique identity.  Already-unique IDs and messages without IDs are left
+    untouched.
+    """
+    seen: dict[str, int] = {}
+    for idx, msg in enumerate(messages):
+        mid = msg.message_id
+        if not mid:
+            continue
+        if mid in seen:
+            # Duplicate — reassign with positional suffix
+            msg.message_id = f"{mid}_i{idx}"
+        else:
+            seen[mid] = idx