iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/agent_middleware/system_reminder.py

@@ -0,0 +1,1107 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""SystemReminderMiddleware — injects ``<system-reminder>`` tags per LLM call.
+
+A ``ChatMiddleware`` that fires before each LLM call in the tool loop.
+It replaces user messages in ``context.messages`` (a per-call shallow copy)
+with enriched versions whose original user contents come first, followed by
+``<system-reminder>`` tags.  What each reminder says, and the state behind
+it, lives in its source (``reminders/``); this module decides when each one
+is sent, records it and fixes the send order.
+
+Reminders stay where they were first sent.  Once a request carrying them is
+established, the reminders a user message received are recorded in its
+``additional_properties`` (``HistoryMarkerKind.SYSTEM_REMINDERS_KEY``), and
+every later call re-renders that record byte-identically — in later turns
+too — so the conversation prefix, and the provider's prompt cache over it,
+survives from one turn to the next.  The message's own contents never hold a
+reminder: ``ChatContext.messages`` is a **shallow copy** of the tool loop's
+``prepped_messages``, so enrichment replaces list elements, never the history
+message objects.
+
+Only reminders not already visible are added to the last user message:
+
+- the turn line (turn-start time, previous-turn context usage) once per
+  turn;
+- event reminders (hooks, workspace file changes, the context-usage warning,
+  which ``reminders.context_usage`` arms) once per turn by text;
+- the profile-switch notice while the latest switch notice the turn shows
+  differs — a switch made before a retry reaches the retried request, and
+  Code → QA → Code → QA across retries sends the last notice again;
+- catalogs — standing context: runtime environment, sub-agent tip, todo
+  list, skill catalog, MCP server instructions, archive-catalog pointer —
+  whenever the latest version of that catalog in view differs: a changed
+  catalog (changed back included), or one whose carrier a context fold took
+  out of view, is sent again, and one no longer offered is replaced by a
+  notice that it no longer applies where it has one.
+
+A call that continues a service-side conversation (``conversation_id``)
+sends only the new messages, so what that conversation holds is out of view:
+the catalogs the last answered call left in it count as in view when the
+next call continues exactly from the handle that answer returned.  Any other
+handle, a failed call, or a fresh middleware sends them again.
+
+A continuation poll adds and records nothing: the provider ignores its
+messages.
+
+Turn reminders are snapshotted at ``prepare_turn()`` and reused for every LLM
+call in that turn.  User-initiated injection/retry may refresh the skill
+catalog before the next model call because a newly added skill is a
+meaningful runtime capability change.  LAST_WORDS is different: it is
+generated by mid-turn compaction, remains dynamic and is never recorded.  Do
+not reintroduce per-call timestamps or other volatile reminder text.
+
+Escaping scope: this middleware defangs ``<system-reminder>`` tags in
+user-role message content only.  Tool-result content (web fetches, file
+reads, sub-agent output) is passed through verbatim — treat reminder-shaped
+text in tool results as untrusted in downstream prompts and rely on the
+model's own judgement, not on this middleware, to discount it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from contextvars import ContextVar
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, Protocol, cast, get_args
+
+from chrys.foundation.models.history_markers import HistoryMarkerKind
+from chrys.foundation.models.turns import opens_turn
+from chrys.kernel import EXCLUDED_KEY, ChatResponse, Message, is_local_history_conversation_id
+from chrys.kernel.middleware import ChatMiddleware
+from chrys.service.profiles.models.schema import DEFAULT_MAX_CONTEXT_TOKENS
+
+from .reminders import ReminderSources, build_sources
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Iterable, Sequence
+
+    from chrys.foundation.models.session_env import SessionEnvironment
+    from chrys.kernel.middleware import ChatContext
+    from chrys.service.context.compaction.last_words_state import LastWordsTurn
+    from chrys.service.context.compaction.spill import SpillQuota
+
+    from .reminders.base import CatalogSource
+    from .reminders.file_change import FileChangeTurn
+    from .reminders.profile_switch import SwitchSnapshot
+
+REMINDER_TAG_OPEN = "<system-reminder>"
+REMINDER_TAG_CLOSE = "</system-reminder>"
+ESCAPED_REMINDER_TAG_OPEN = "&lt;system-reminder&gt;"
+ESCAPED_REMINDER_TAG_CLOSE = "&lt;/system-reminder&gt;"
+
+LAST_WORDS_PREFIX = "[LAST_WORDS] "
+"""Opens every LAST_WORDS block (rendered by ``compaction.last_words_state``).
+
+Load-bearing: ``refresh_last_words_reminder`` finds the blocks to replace by
+it, so it must stay byte-identical."""
+
+
+def escape_system_reminder_tags(text: str) -> str:
+    """Defang user-authored reminder tags before text reaches the model."""
+    return text.replace(REMINDER_TAG_OPEN, ESCAPED_REMINDER_TAG_OPEN).replace(
+        REMINDER_TAG_CLOSE,
+        ESCAPED_REMINDER_TAG_CLOSE,
+    )
+
+
+def wrap_system_reminder(content: str) -> str:
+    """Wrap *content* in ``<system-reminder>`` tags."""
+    return f"{REMINDER_TAG_OPEN}\n{escape_system_reminder_tags(content)}\n{REMINDER_TAG_CLOSE}"
+
+
+_ReminderKind = Literal["turn", "event", "switch", "catalog"]
+_REMINDER_KINDS: frozenset[str] = frozenset(get_args(_ReminderKind))
+
+
+@dataclass(frozen=True, slots=True)
+class _ReminderItem:
+    """One reminder text and the rule that decides whether it is sent again.
+
+    ``turn``: turn-start snapshot, sent once per turn as a group.  ``event``:
+    sent once per turn per text.  ``switch``: the profile-switch notice, sent
+    while the turn's latest switch notice differs.  ``catalog``: standing
+    context, sent while the latest version of the catalog *name* in view
+    differs.  Records written before the runtime environment, todo list and
+    archive pointer became catalogs hold them as ``turn`` items.
+    """
+
+    kind: _ReminderKind
+    text: str
+    name: str | None = None
+    """Which catalog a ``catalog`` item is a version of; None for other kinds."""
+
+    def to_record(self) -> dict[str, str]:
+        record = {"kind": self.kind, "text": self.text}
+        if self.name is not None:
+            record["name"] = self.name
+        return record
+
+
+def _recorded_reminders(properties: Mapping[str, Any]) -> list[_ReminderItem]:
+    """Return the reminders recorded on a user message, skipping malformed entries."""
+    raw = properties.get(HistoryMarkerKind.SYSTEM_REMINDERS_KEY)
+    if not isinstance(raw, list):
+        return []
+    items: list[_ReminderItem] = []
+    for entry in raw:
+        if not isinstance(entry, Mapping):
+            continue
+        kind = entry.get("kind")
+        text = entry.get("text")
+        name = entry.get("name")
+        # Type checks first: a persisted list or object ``kind`` is unhashable.
+        if isinstance(kind, str) and kind in _REMINDER_KINDS and isinstance(text, str) and text:
+            items.append(_ReminderItem(cast("_ReminderKind", kind), text, name if isinstance(name, str) else None))
+    return items
+
+
+def _records_of(messages: Sequence[Message]) -> list[list[_ReminderItem]]:
+    """Each message's recorded reminders, parsed once per call (none for non-user roles)."""
+    return [
+        _recorded_reminders(message.additional_properties) if message.role == "user" else [] for message in messages
+    ]
+
+
+def _record_reminders(properties: dict[str, Any], items: Sequence[_ReminderItem]) -> None:
+    """Record *items* on a message, always as a new list.
+
+    Retry rollback restores a props dict from a one-level copy that shares
+    its list values, so the stored list itself is never mutated.
+    """
+    properties[HistoryMarkerKind.SYSTEM_REMINDERS_KEY] = [item.to_record() for item in items]
+
+
+def _is_visible(message: Message) -> bool:
+    return not message.additional_properties.get(EXCLUDED_KEY, False)
+
+
+def _catalog_key(item: _ReminderItem) -> str:
+    """The catalog *item* is a version of; an unnamed entry is its own catalog."""
+    return item.name if item.name is not None else item.text
+
+
+def _latest_switch_notice(items: Iterable[_ReminderItem]) -> str | None:
+    """The last profile-switch notice among *items*, if any."""
+    latest: str | None = None
+    for item in items:
+        if item.kind == "switch":
+            latest = item.text
+    return latest
+
+
+def _latest_visible_catalogs(
+    messages: Sequence[Message],
+    records: Sequence[Sequence[_ReminderItem]],
+) -> dict[str, str]:
+    """The latest version of each catalog recorded on user messages still in view.
+
+    An older version stays in view after a newer one was sent, so a catalog
+    compares with its latest version only: A → B → A must send A again.
+    """
+    latest: dict[str, str] = {}
+    for message, items in zip(messages, records, strict=True):
+        if message.role != "user" or not _is_visible(message):
+            continue
+        for item in items:
+            if item.kind == "catalog":
+                latest[_catalog_key(item)] = item.text
+    return latest
+
+
+def _withdrawn_notices(sources: Iterable[CatalogSource]) -> dict[str, str]:
+    """Each catalog's withdrawal notice by record name, for the catalogs that have one.
+
+    A catalog that disappeared (its provider went away or has nothing to say)
+    still shows its last version on an earlier message, so the model is told
+    it no longer applies.
+    """
+    return {source.name: source.withdrawn for source in sources if source.withdrawn is not None}
+
+
+def _catalog_updates(
+    latest: Mapping[str, str],
+    current: Sequence[_ReminderItem],
+    withdrawn_notices: Mapping[str, str],
+) -> list[_ReminderItem]:
+    """The catalogs to send so that the latest version of each in view is current.
+
+    A changed catalog (changed back included) goes out again; one no longer
+    offered is replaced by its notice in *withdrawn_notices* while an older
+    version of it is still in view.
+    """
+    updates = [item for item in current if latest.get(_catalog_key(item)) != item.text]
+    offered = {_catalog_key(item) for item in current}
+    for name, text in latest.items():
+        withdrawn = withdrawn_notices.get(name)
+        if name not in offered and withdrawn is not None and text != withdrawn:
+            updates.append(_ReminderItem("catalog", withdrawn, name))
+    return updates
+
+
+def _is_continuation_poll(context: ChatContext) -> bool:
+    """A poll retrieves an already-created response; the provider ignores its messages."""
+    options = context.options
+    return options is not None and options.get("continuation_token") is not None
+
+
+def _service_handle(conversation_id: object) -> str | None:
+    """*conversation_id* when it names a service-side conversation."""
+    if isinstance(conversation_id, str) and conversation_id and not is_local_history_conversation_id(conversation_id):
+        return conversation_id
+    return None
+
+
+@dataclass
+class TurnReminderState:
+    """Intentionally mutable reminder state shared across one logical turn.
+
+    ContextVar values are copied into child tasks, so the middleware stores one
+    state object and mutates it in place.  That lets Phase 4 LAST_WORDS updates
+    made inside an agent child task remain visible to sibling retry/resume tasks
+    that continue the same logical turn.
+    """
+
+    turn_reminders: tuple[str, ...] = ()
+    """Turn-start snapshot sent once per turn: time and previous-turn usage."""
+    context_warning: str | None = None
+    """The context-usage warning, when this turn crosses the threshold."""
+    event_reminders: tuple[str, ...] = ()
+    """Hook and skill-reference reminders queued for this turn."""
+    runtime_hint: str | None = None
+    sub_agent_tip: str | None = None
+    todo: str | None = None
+    """Turn-start todo list (None when empty)."""
+    skill_catalog: str | None = None
+    mcp_instructions: str | None = None
+    switch: SwitchSnapshot | None = None
+    """The switch this turn announces, with its notice: a retry keeps the
+    opener's turn group, and the notice must still reach the retried request."""
+    file_change: FileChangeTurn | None = None
+    """The workspace file-change notice drained for this turn."""
+    last_words: LastWordsTurn | None = None
+    """The Phase 4 slot ``compaction.last_words_state.LastWordsState`` owns; None until it writes one."""
+
+
+class LastWordsPort(Protocol):
+    """The LAST_WORDS state this middleware renders (``compaction.last_words_state.LastWordsState``)."""
+
+    @property
+    def turns(self) -> ReminderTurns:
+        """The turn holder the state reads and writes; the middleware keeps its turns there too."""
+        ...
+
+    def begin_turn(self, previous: TurnReminderState | None, *, preserve: bool) -> LastWordsTurn:
+        """The new turn's LAST_WORDS slot, given the previous turn's container."""
+        ...
+
+    def discard_restored(self) -> None:
+        """Drop the restored stash: the turn ``begin_turn`` just built took it or discarded it."""
+        ...
+
+    def record_paths(self, turn: LastWordsTurn) -> set[str]:
+        """The record paths *turn*'s manifest lists."""
+        ...
+
+    def render(self) -> list[str]:
+        """The LAST_WORDS blocks the next call appends, unwrapped."""
+        ...
+
+
+class ReminderTurns:
+    """Where one middleware keeps its per-turn reminder container.
+
+    The container lives in a ContextVar, so a task sees the turn its caller
+    prepared, and in an active-turn fallback: the engine runs one main turn
+    per middleware at a time, and a child or sibling task started under an
+    empty context recovers that turn's container from it.
+    """
+
+    def __init__(self) -> None:
+        self._local: ContextVar[TurnReminderState | None] = ContextVar(
+            f"chrys_reminder_turns_{id(self)}",
+            default=None,
+        )
+        self._active: TurnReminderState | None = None
+
+    @property
+    def active(self) -> TurnReminderState | None:
+        """The prepared turn's container, in any task."""
+        return self._active
+
+    def local(self) -> TurnReminderState | None:
+        """This task's container, without the active-turn fallback."""
+        return self._local.get()
+
+    def current(self) -> TurnReminderState | None:
+        """This task's container, else the active turn's."""
+        return self._local.get() or self._active
+
+    def ensure(self) -> TurnReminderState:
+        """The current container, or a new empty one for this task only."""
+        state = self.current()
+        if state is None:
+            state = TurnReminderState()
+            self._local.set(state)
+        return state
+
+    def install(self, state: TurnReminderState) -> None:
+        """Make *state* this task's container and the active turn's."""
+        self._local.set(state)
+        self._active = state
+
+    def install_local(self, state: TurnReminderState) -> None:
+        """Make *state* this task's container only."""
+        self._local.set(state)
+
+    def clear(self) -> None:
+        """Forget the active turn and this task's container."""
+        self._local.set(None)
+        self._active = None
+
+
+@dataclass(frozen=True, eq=False)
+class CurrentRunReminderScope:
+    """Opaque service-owned token for one logical main-agent run."""
+
+    scope_id: int
+
+
+@dataclass(frozen=True, eq=False)
+class CurrentRunReminderTarget:
+    """Opaque service-owned current-run reminder target captured by orchestration."""
+
+    scope: CurrentRunReminderScope
+    phase: Literal["pre_prepare", "prepared"]
+    generation: int
+    state: TurnReminderState | None = None
+
+
+class SystemReminderMiddleware(ChatMiddleware):
+    """Appends trailing ``<system-reminder>`` content before each LLM call.
+
+    Each LLM call in the tool loop sees fresh enriched user messages whose
+    original user contents come first, followed by the reminders each one
+    carried when first sent; the last user message also gets the reminders
+    not yet in view.  Exact reserved reminder tags in user-role text are
+    escaped in the per-call ``ChatContext.messages`` copy; tool results are
+    passed through unchanged.  Message contents in ``prepped_messages`` and
+    session state are never modified — only the reminder record in a user
+    message's ``additional_properties``.
+    """
+
+    def __init__(
+        self,
+        runtime: SessionEnvironment | None = None,
+        *,
+        max_context_tokens: int = DEFAULT_MAX_CONTEXT_TOKENS,
+        warn_threshold_pct: float = 0.50,
+        sub_agent_names: list[str] | None = None,
+        shell_tool_enabled: bool = False,
+        tool_names: list[str] | None = None,
+        session_root: Path | None = None,
+        file_read_available: bool = False,
+        spill_quota: SpillQuota | None = None,
+        catalog_pointer_enabled: bool = True,
+        skill_catalog_provider: Callable[[], str | None] | None = None,
+        todo_state_provider: Callable[[], str | None] | None = None,
+        mcp_instructions_provider: Callable[[], str | None] | None = None,
+        file_change_provider: Callable[[], str | None] | None = None,
+        last_words: LastWordsPort | None = None,
+    ) -> None:
+        """*last_words* comes from ``create_reminder``; the middleware keeps its turns on the state's holder.
+
+        Without *last_words* the middleware renders no LAST_WORDS block and
+        cannot be bound to a compaction strategy.
+        """
+        self._sources = build_sources(
+            runtime=runtime,
+            max_context_tokens=max_context_tokens,
+            warn_threshold_pct=warn_threshold_pct,
+            shell_tool_enabled=shell_tool_enabled,
+            sub_agent_names=sub_agent_names,
+            todo_state_provider=todo_state_provider,
+            skill_catalog_provider=skill_catalog_provider,
+            mcp_instructions_provider=mcp_instructions_provider,
+            file_change_provider=file_change_provider,
+            tool_names=tool_names,
+            session_root=session_root,
+            file_read_available=file_read_available,
+            spill_quota=spill_quota,
+            catalog_pointer_enabled=catalog_pointer_enabled,
+        )
+        sources = self._sources
+        self._withdrawn_notices = _withdrawn_notices(
+            (sources.runtime_env, sources.sub_agents, sources.todo, sources.skills, sources.mcp)
+        )
+        # The catalogs a service-side conversation holds, keyed by the handle
+        # its last answered call returned (see the module docstring).
+        self._held_catalogs: tuple[str, dict[str, str]] | None = None
+        self._pending_hook_reminders: list[str] = []
+        self._next_current_run_scope_id = 1
+        self._current_run_scopes: set[CurrentRunReminderScope] = set()
+        self._pending_current_run_hook_reminders: dict[CurrentRunReminderScope, list[str]] = {}
+        self._active_turn_scope: CurrentRunReminderScope | None = None
+        self._current_run_reminder_generation = 0
+        # One holder for both, so the note Phase 4 writes is in the container
+        # prepare_turn installs.
+        self._turns = last_words.turns if last_words is not None else ReminderTurns()
+        self._last_words = last_words
+
+    @property
+    def sources(self) -> ReminderSources:
+        """The content sources this middleware composes; callers reach the switch through it."""
+        return self._sources
+
+    def prepare_turn(
+        self,
+        *,
+        reminder_scope: CurrentRunReminderScope | None = None,
+        usage: Mapping[str, Any] | None = None,
+        preserve_last_words: bool = False,
+        preserve_turn_reminders: bool = False,
+    ) -> None:
+        """Prepare reminder state before ``executor.run()`` or retry/resume.
+
+        ``preserve_last_words`` carries Phase 4 progress across retries.
+        ``preserve_turn_reminders`` keeps runtime/usage/switch text
+        byte-identical for KV-cache continuity on retry.
+        """
+        previous = self._turns.current()
+        snapshot_catalog_pointer = False
+        if preserve_turn_reminders and previous is not None:
+            snapshot = TurnReminderState(
+                turn_reminders=previous.turn_reminders,
+                context_warning=previous.context_warning,
+                event_reminders=previous.event_reminders,
+                runtime_hint=previous.runtime_hint,
+                sub_agent_tip=previous.sub_agent_tip,
+                todo=previous.todo,
+                skill_catalog=previous.skill_catalog,
+                mcp_instructions=previous.mcp_instructions,
+                switch=previous.switch,
+            )
+        else:
+            snapshot = self._snapshot_turn_reminders(usage=usage or {})
+            snapshot.skill_catalog = self._sources.skills.snapshot()
+            snapshot.mcp_instructions = self._sources.mcp.snapshot()
+            snapshot_catalog_pointer = True
+        event_reminders = snapshot.event_reminders
+        self._current_run_reminder_generation += 1
+        if reminder_scope is not None:
+            scoped_reminders = self._pending_current_run_hook_reminders.pop(reminder_scope, [])
+            if scoped_reminders:
+                event_reminders = (*event_reminders, *scoped_reminders)
+        if self._pending_hook_reminders:
+            event_reminders = (*event_reminders, *self._pending_hook_reminders)
+            self._pending_hook_reminders.clear()
+        last_words = (
+            self._last_words.begin_turn(previous, preserve=preserve_last_words)
+            if self._last_words is not None
+            else None
+        )
+        pointer = self._sources.archive_pointer
+        if snapshot_catalog_pointer:
+            restored_pointer_count = pointer.restored_record_count if preserve_last_words and previous is None else None
+            if restored_pointer_count is not None:
+                pointer.capture(restored_pointer_count)
+            else:
+                # Legacy restored sessions did not persist the turn-start
+                # snapshot. Excluding the bounded active manifest is the best
+                # compatible approximation, but new saves never rely on it.
+                active_manifest_paths = (
+                    self._last_words.record_paths(last_words)
+                    if self._last_words is not None and last_words is not None
+                    else set()
+                )
+                pointer.capture_live(excluded_relative_paths=active_manifest_paths)
+        # The restored stashes are single-shot either way: a preserving turn
+        # consumed them; a fresh turn discards them (matching the in-process
+        # new-turn semantics).
+        pointer.discard_restored()
+        if self._last_words is not None:
+            self._last_words.discard_restored()
+        state = replace(
+            snapshot,
+            event_reminders=event_reminders,
+            file_change=self._sources.file_change.drain(),
+            last_words=last_words,
+        )
+        self._turns.install(state)
+        self._active_turn_scope = reminder_scope
+        self._sources.profile_switch.begin_turn()
+
+    def take_undelivered_file_change(self) -> str | None:
+        """Pop the prepared notice unless a model-bound request already carried it."""
+        state = self._turns.current()
+        if state is None:
+            return None
+        notice = state.file_change
+        state.file_change = None
+        if notice is None or notice.delivered:
+            return None
+        return notice.text
+
+    def create_current_run_scope(self) -> CurrentRunReminderScope:
+        """Allocate a service-owned reminder scope for a logical main-agent run."""
+        scope = CurrentRunReminderScope(self._next_current_run_scope_id)
+        self._next_current_run_scope_id += 1
+        self._current_run_scopes.add(scope)
+        return scope
+
+    def capture_current_run_target(
+        self,
+        reminder_scope: CurrentRunReminderScope,
+    ) -> CurrentRunReminderTarget | None:
+        """Capture a current-run reminder target if *reminder_scope* is still valid."""
+        if reminder_scope not in self._current_run_scopes:
+            return None
+        active = self._turns.active
+        if self._active_turn_scope is reminder_scope and active is not None:
+            return CurrentRunReminderTarget(
+                scope=reminder_scope,
+                phase="prepared",
+                generation=self._current_run_reminder_generation,
+                state=active,
+            )
+        return CurrentRunReminderTarget(
+            scope=reminder_scope,
+            phase="pre_prepare",
+            generation=self._current_run_reminder_generation,
+        )
+
+    def queue_hook_reminders_for_current_run(
+        self,
+        target: CurrentRunReminderTarget,
+        reminders: list[str],
+    ) -> bool:
+        """Queue hook reminders only if the captured current-run target is still valid."""
+        if not self._is_current_run_target_valid(target):
+            return False
+        clean = [reminder for reminder in reminders if reminder]
+        if not clean:
+            return True
+        if target.phase == "prepared" and target.state is not None:
+            target.state.event_reminders = (*target.state.event_reminders, *clean)
+            return True
+        active = self._turns.active
+        if self._active_turn_scope is target.scope and active is not None:
+            active.event_reminders = (*active.event_reminders, *clean)
+            return True
+        self._pending_current_run_hook_reminders.setdefault(target.scope, []).extend(clean)
+        return True
+
+    def update_skill_catalog_for_current_run(self, target: CurrentRunReminderTarget) -> bool:
+        """Refresh the skill catalog only if the captured current-run target is current."""
+        if not self._is_current_run_target_valid(target):
+            return False
+        active = self._turns.active
+        if target.phase == "prepared" and target.state is not None:
+            target.state.skill_catalog = self._sources.skills.snapshot()
+        elif self._active_turn_scope is target.scope and active is not None:
+            active.skill_catalog = self._sources.skills.snapshot()
+        return True
+
+    def set_skill_catalog_for_current_run(
+        self,
+        target: CurrentRunReminderTarget,
+        skill_catalog: str | None,
+    ) -> bool:
+        """Set the skill catalog only if the captured current-run target is current."""
+        if not self._is_current_run_target_valid(target):
+            return False
+        active = self._turns.active
+        if target.phase == "prepared" and target.state is not None:
+            target.state.skill_catalog = skill_catalog
+        elif self._active_turn_scope is target.scope and active is not None:
+            active.skill_catalog = skill_catalog
+        return True
+
+    def is_current_run_target_valid(self, target: CurrentRunReminderTarget) -> bool:
+        """Return whether a captured current-run reminder target is still valid."""
+        return self._is_current_run_target_valid(target)
+
+    def expire_current_run_scope(self, reminder_scope: CurrentRunReminderScope) -> None:
+        """Expire a current-run scope and discard stale reminders for it."""
+        self._current_run_scopes.discard(reminder_scope)
+        self._pending_current_run_hook_reminders.pop(reminder_scope, None)
+        if self._active_turn_scope is reminder_scope:
+            self._active_turn_scope = None
+            self._turns.clear()
+
+    def renders_last_words(self, state: object) -> bool:
+        """Whether *state* is the LAST_WORDS state this middleware renders."""
+        return self._last_words is not None and self._last_words is state
+
+    def refresh_last_words_reminder(self, messages: list[Any]) -> int | None:
+        """Rewrite the ``[LAST_WORDS]`` reminder on a per-call message list.
+
+        Phase 4 compaction runs *below* this middleware (inside the client's
+        message prep), so the LLM call that triggered it was enriched before
+        the new note existed — without this refresh, that call would go out
+        with its tool-call history dropped but only a stale note (or none)
+        in its place, and the model would restart the task from scratch.
+
+        Rebuilds the last user message with the current note rendered
+        exactly as the next call's enrichment will render it, keeping the
+        request prefix byte-stable across calls.  The list entry is
+        *replaced* with a fresh ``Message`` — the existing object is never
+        mutated, because when enrichment was skipped it is the live history
+        message.  ``additional_properties`` is shared by reference so
+        exclusion flags keep writing through to the history object; the
+        caller must recompute any token annotation riding in it, since the
+        shared count still describes the pre-refresh contents.  Returns the
+        index of the replaced entry, or ``None`` when the list was left
+        unmodified.
+        """
+        message, idx = self._find_user_message(messages)
+        if message is None:
+            return None
+        reminders = self._last_words_reminders()
+        kept = [c for c in message.contents if not self._is_last_words_reminder_content(c)]
+        if len(kept) == len(message.contents) and not reminders:
+            return None
+        messages[idx] = self._rebuild(message, [*kept, *(wrap_system_reminder(r) for r in reminders)])
+        return idx
+
+    def restore_folded_reminders(self, messages: list[Message]) -> int | None:
+        """Re-send catalogs (standing context) a context fold just took out of view on this call.
+
+        A catalog is sent once and then only re-rendered from the user
+        message that recorded it.  Folds (``compress_context``, Phase 3) run
+        *below* this middleware, inside the client's message prep, and
+        exclude whole earlier turns: when the carrier goes, the call that
+        triggered the fold would otherwise go out without the catalog.  The
+        missing catalogs are appended to the last user message, before any
+        LAST_WORDS block, and recorded on it, so later calls and turns render
+        them there.
+
+        The list entry is replaced with a fresh ``Message`` sharing the
+        original's ``additional_properties``, as ``refresh_last_words_reminder``
+        does; the caller must recompute token annotations from the returned
+        index.  Returns ``None`` when nothing was missing.
+        """
+        message, idx = self._find_user_message(messages)
+        state = self._turns.current()
+        if message is None or state is None or not _is_visible(message):
+            return None
+        missing = _catalog_updates(
+            _latest_visible_catalogs(messages, self._rendered_records(messages)),
+            self._catalog_items(state),
+            self._withdrawn_notices,
+        )
+        if not missing:
+            return None
+        kept = [c for c in message.contents if not self._is_last_words_reminder_content(c)]
+        last_words = [c for c in message.contents if self._is_last_words_reminder_content(c)]
+        messages[idx] = self._rebuild(
+            message, [*kept, *(wrap_system_reminder(item.text) for item in missing), *last_words]
+        )
+        _record_reminders(
+            message.additional_properties,
+            [*_recorded_reminders(message.additional_properties), *missing],
+        )
+        return idx
+
+    @staticmethod
+    def _is_last_words_reminder_content(content: Any) -> bool:
+        """Whether a content item is a middleware-authored LAST_WORDS reminder.
+
+        User-authored reminder tags are escaped during enrichment, so a raw
+        wrapped ``[LAST_WORDS]`` block can only come from the LAST_WORDS state.
+        """
+        return (
+            content.type == "text"
+            and content.text is not None
+            and content.text.startswith(f"{REMINDER_TAG_OPEN}\n{LAST_WORDS_PREFIX}")
+        )
+
+    def queue_hook_reminders(self, reminders: list[str], *, for_next_turn: bool = False) -> None:
+        """Queue hook-provided reminders for the current or next user turn."""
+        clean = [r for r in reminders if r]
+        if not clean:
+            return
+        state = None if for_next_turn else self._turns.current()
+        if state is not None:
+            state.event_reminders = (*state.event_reminders, *clean)
+            return
+        self._pending_hook_reminders.extend(clean)
+
+    def queue_drained_injection_reminders(self, reminders: list[str]) -> None:
+        """Queue a drained injection's hook/skill reminders for the call that sends it.
+
+        The injection middleware runs before this one in the same call, so
+        they land on the injected message; an injection that never reaches a
+        call (cancelled, or returned to the input box) never queues them.
+        """
+        clean = [reminder for reminder in reminders if reminder]
+        if clean:
+            state = self._turns.ensure()
+            state.event_reminders = (*state.event_reminders, *clean)
+
+    def update_skill_catalog_for_active_turn(self) -> None:
+        """Refresh the active turn's skill-catalog reminder from the provider."""
+        state = self._turns.current()
+        if state is None:
+            return
+        state.skill_catalog = self._sources.skills.snapshot()
+
+    # ------------------------------------------------------------------
+    # ChatMiddleware interface
+    # ------------------------------------------------------------------
+
+    async def process(
+        self,
+        context: ChatContext,
+        call_next: Callable[[], Awaitable[None]],
+    ) -> None:
+        reminder_items = self._build_reminder_items()
+        last_words_reminders = self._last_words_reminders()
+        applied_switch: SwitchSnapshot | None = None
+        # Replace user messages in the per-call shallow copy only.  This
+        # renders recorded reminders and defangs user-authored reminder tags
+        # without modifying the tool loop's prepped_messages or
+        # SessionContext.input_messages.  Tool-result messages are
+        # intentionally not escaped here.
+        # ``ChatMiddlewareLayer`` always gives ``ChatContext`` a fresh mutable
+        # list; the kernel constructor's public annotation is the broader
+        # ``Sequence`` accepted at its external boundary.
+        messages = cast("list[Message]", context.messages)
+        target, target_idx = self._find_user_message(messages)
+        if target is not None and (not _is_visible(target) or _is_continuation_poll(context)):
+            # An excluded message never reaches the wire, and a poll's
+            # messages are ignored: recording on either would claim a
+            # delivery that never happened.
+            target, target_idx = None, -1
+        records = self._rendered_records(messages)
+        handle = _service_handle(context.options.get("conversation_id") if context.options is not None else None)
+        held = self._held_catalogs[1] if self._held_catalogs is not None and self._held_catalogs[0] == handle else {}
+        in_view = {**held, **_latest_visible_catalogs(messages, records)}
+        turn_recorded = self._turn_recorded(messages, records, target_idx) if target is not None else []
+        new_items = self._unsent_reminders(in_view, turn_recorded, reminder_items) if target is not None else []
+        for msg_idx, message in enumerate(messages):
+            if message.role != "user" or not _is_visible(message):
+                # Excluded messages never reach the wire; nothing to render.
+                continue
+            reminders = [item.text for item in records[msg_idx]]
+            message_last_words_reminders: list[str] = []
+            if msg_idx == target_idx:
+                reminders.extend(item.text for item in new_items)
+                message_last_words_reminders = last_words_reminders
+            if reminders or message_last_words_reminders or self._has_system_reminder_tags(message):
+                messages[msg_idx] = self._create_enriched(message, reminders, message_last_words_reminders)
+        if target is not None:
+            if new_items:
+                context.request_message_observers.append(
+                    self._record_on_delivery(target.additional_properties, tuple(new_items))
+                )
+            state = self._turns.current()
+            if state is not None and any(
+                item.kind == "event" and item.text == state.context_warning for item in new_items
+            ):
+                context.request_message_observers.append(self._sources.context_warning.delivered)
+            if state is not None and state.file_change is not None:
+                # Delivered means an established provider request, not
+                # a completed middleware chain: lazy streaming inner
+                # middleware returns a proxy from call_next() and only
+                # reaches the final handler at first stream
+                # consumption. Observers run immediately before every
+                # final-handler invocation, so a run cancelled before
+                # consumption keeps the notice requeueable.
+                context.request_message_observers.append(state.file_change.mark_delivered)
+            if (
+                state is not None
+                and state.switch is not None
+                and _latest_switch_notice((*turn_recorded, *new_items)) == state.switch.notice
+            ):
+                # Only a switch whose notice is the latest this request
+                # carries (sent now or earlier in the turn) is consumed.
+                applied_switch = state.switch
+
+        polled = _is_continuation_poll(context)
+        if not polled:
+            # Unknown until this call is answered: a failed call may or may
+            # not have left its catalogs in the conversation.
+            self._held_catalogs = None
+        await call_next()
+        if not polled:
+            carried = in_view | {_catalog_key(item): item.text for item in new_items if item.kind == "catalog"}
+            self._hold_catalogs_on_answer(context, carried)
+        if applied_switch is not None:
+            self._sources.profile_switch.carried(applied_switch)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _build_reminders(self) -> list[str]:
+        """Every reminder text this turn offers, whether or not already sent."""
+        return [item.text for item in self._build_reminder_items()]
+
+    def _build_reminder_items(self) -> list[_ReminderItem]:
+        state = self._turns.local()
+        if state is None:
+            # Fallback for direct middleware use without ``prepare_turn()``.
+            # It deliberately avoids consuming pending profile switches:
+            # switch reminders are turn-scoped and must be snapshotted by
+            # the caller that starts the turn.
+            state = self._snapshot_turn_reminders(usage={}, include_pending_switch=False)
+            state.skill_catalog = self._sources.skills.snapshot()
+            state.mcp_instructions = self._sources.mcp.snapshot()
+            self._turns.install_local(state)
+        return self._compose_items(state)
+
+    def _compose_items(self, state: TurnReminderState) -> list[_ReminderItem]:
+        """Every reminder *state* offers, in send order, each with the kind that decides its re-send.
+
+        The one place the send order is written: the turn line, the
+        context-usage warning, the profile-switch notice, the event inbox in
+        queue order, the workspace file change, then the catalogs in their
+        fixed order.  ``_unsent_reminders`` keeps this order and appends the
+        withdrawals; LAST_WORDS blocks go after everything, unrecorded.
+        """
+        items = [_ReminderItem("turn", text) for text in state.turn_reminders]
+        if state.context_warning:
+            items.append(_ReminderItem("event", state.context_warning))
+        if state.switch is not None:
+            items.append(_ReminderItem("switch", state.switch.notice))
+        items.extend(_ReminderItem("event", text) for text in state.event_reminders)
+        if state.file_change is not None:
+            items.append(_ReminderItem("event", state.file_change.text))
+        items.extend(self._catalog_items(state))
+        return items
+
+    def _catalog_items(self, state: TurnReminderState) -> list[_ReminderItem]:
+        """The standing context this turn offers, one item per catalog name."""
+        return [
+            _ReminderItem("catalog", text, name)
+            for name, text in (
+                (self._sources.runtime_env.name, state.runtime_hint),
+                (self._sources.sub_agents.name, state.sub_agent_tip),
+                (self._sources.todo.name, state.todo),
+                (self._sources.skills.name, state.skill_catalog),
+                (self._sources.mcp.name, state.mcp_instructions),
+                (self._sources.archive_pointer.name, self._sources.archive_pointer.current_text()),
+            )
+            if text
+        ]
+
+    @staticmethod
+    def _turn_recorded(
+        messages: list[Message],
+        records: list[list[_ReminderItem]],
+        target_idx: int,
+    ) -> list[_ReminderItem]:
+        """Reminders recorded on the current turn's user messages still in view.
+
+        Messages a fold excluded (or left out of the list entirely) no longer
+        show theirs.  The current turn runs from its opener to the last user
+        message, injected and resumed messages included; with no opener in
+        the list, from its start.
+        """
+        turn_start = next((i for i in range(target_idx, -1, -1) if opens_turn(messages[i])), 0)
+        return [
+            item
+            for idx in range(turn_start, target_idx + 1)
+            if messages[idx].role == "user" and _is_visible(messages[idx])
+            for item in records[idx]
+        ]
+
+    def _unsent_reminders(
+        self,
+        catalogs_in_view: Mapping[str, str],
+        turn_recorded: list[_ReminderItem],
+        items: list[_ReminderItem],
+    ) -> list[_ReminderItem]:
+        """Return the reminders the last user message still has to carry.
+
+        Only reminders in view count as sent: *turn_recorded* for turn, event
+        and switch reminders, *catalogs_in_view* (the latest version of each)
+        for catalogs.
+        """
+        turn_started = any(item.kind == "turn" for item in turn_recorded)
+        turn_texts = {item.text for item in turn_recorded}
+        latest_switch = _latest_switch_notice(turn_recorded)
+        catalogs = _catalog_updates(
+            catalogs_in_view,
+            [item for item in items if item.kind == "catalog"],
+            self._withdrawn_notices,
+        )
+        unsent: list[_ReminderItem] = []
+        for item in items:
+            if item.kind == "turn":
+                sent = turn_started
+            elif item.kind == "switch":
+                # Switches compare with the turn's latest one only: switching
+                # Code → QA → Code → QA across retries repeats an earlier text.
+                sent = latest_switch == item.text
+                latest_switch = item.text
+            elif item.kind == "event":
+                # Two hooks can queue the same text; it still goes once.
+                sent = item.text in turn_texts
+                turn_texts.add(item.text)
+            else:
+                sent = item not in catalogs
+            if not sent:
+                unsent.append(item)
+        # Withdrawal notices for catalogs no longer offered go last.
+        unsent.extend(item for item in catalogs if item not in items)
+        return unsent
+
+    def _rendered_records(self, messages: Sequence[Message]) -> list[list[_ReminderItem]]:
+        """Each message's recorded reminders as this session renders them, parsed once per call."""
+        return [[self._rendered(item) for item in items] for items in _records_of(messages)]
+
+    def _rendered(self, item: _ReminderItem) -> _ReminderItem:
+        """A recorded reminder as this session renders it.
+
+        A recorded archive pointer names this session's catalog
+        (``ArchivePointerSource.retarget``).  Comparisons read the rendered
+        text too, so a forked or moved session does not send it again.
+        """
+        pointer = self._sources.archive_pointer
+        is_pointer_kind = item.kind == "turn" or (item.kind == "catalog" and item.name == pointer.name)
+        retargeted = pointer.retarget(item.text) if is_pointer_kind else None
+        if retargeted is None:
+            return item
+        return replace(item, text=retargeted)
+
+    def _hold_catalogs_on_answer(self, context: ChatContext, carried: dict[str, str]) -> None:
+        """Remember *carried* under the handle the answer to this call returns."""
+
+        def _hold(response: ChatResponse) -> ChatResponse:
+            handle = _service_handle(response.conversation_id)
+            self._held_catalogs = (handle, carried) if handle is not None else None
+            return response
+
+        result = context.result
+        if isinstance(result, ChatResponse):
+            _hold(result)
+        elif result is not None:
+            # A stream is answered once it finalizes.
+            context.stream_result_hooks.append(_hold)
+
+    @staticmethod
+    def _record_on_delivery(
+        properties: dict[str, Any],
+        items: tuple[_ReminderItem, ...],
+    ) -> Callable[[Sequence[Message]], None]:
+        """Return a request observer that records *items* once a request carries them.
+
+        Observers run before every final-handler invocation, and again with
+        the prepared provider request; a validation retry re-sends the same
+        enriched list.  The record is appended once per enrichment.
+        """
+        recorded = False
+
+        def _observe(_messages: Sequence[Message]) -> None:
+            nonlocal recorded
+            if recorded:
+                return
+            recorded = True
+            _record_reminders(properties, [*_recorded_reminders(properties), *items])
+
+        return _observe
+
+    def _is_current_run_target_valid(self, target: CurrentRunReminderTarget) -> bool:
+        if target.scope not in self._current_run_scopes:
+            return False
+        if target.phase == "prepared":
+            return self._active_turn_scope is target.scope and self._turns.active is target.state
+        if self._active_turn_scope is target.scope and self._turns.active is not None:
+            return True
+        return self._active_turn_scope is None and target.generation == self._current_run_reminder_generation
+
+    def _snapshot_turn_reminders(
+        self,
+        *,
+        usage: Mapping[str, Any],
+        include_pending_switch: bool = True,
+    ) -> TurnReminderState:
+        """Snapshot the turn-level reminders, with the pending switch and its notice if included.
+
+        The returned state holds the turn line, the context-usage warning,
+        the standing runtime/sub-agent/todo context and the switch; the
+        caller adds the rest.
+        """
+        state = TurnReminderState(
+            runtime_hint=self._sources.runtime_env.snapshot(),
+            sub_agent_tip=self._sources.sub_agents.snapshot(),
+            todo=self._sources.todo.snapshot(),
+        )
+
+        # The turn line: time at turn start and the previous turn's usage.
+        turn_line = self._sources.turn_line.snapshot(usage)
+        state.context_warning = self._sources.context_warning.snapshot(usage)
+        if turn_line is not None:
+            state.turn_reminders = (turn_line,)
+
+        # Profile switch (stable for this turn; sent as an event)
+        if include_pending_switch:
+            state.switch = self._sources.profile_switch.snapshot()
+
+        return state
+
+    def _last_words_reminders(self) -> list[str]:
+        """The LAST_WORDS blocks this call appends after every other reminder."""
+        return self._last_words.render() if self._last_words is not None else []
+
+    @staticmethod
+    def _find_user_message(messages: list[Any]) -> tuple[Message | None, int]:
+        """Return the last user ``Message`` and its index, or ``(None, -1)``."""
+        for i in range(len(messages) - 1, -1, -1):
+            if messages[i].role == "user":
+                return messages[i], i
+        return None, -1
+
+    @staticmethod
+    def _has_system_reminder_tags(message: Message) -> bool:
+        """Return true if a message contains raw reserved reminder tags."""
+        for c in message.contents:
+            if (
+                c.type == "text"
+                and c.text is not None
+                and (REMINDER_TAG_OPEN in c.text or REMINDER_TAG_CLOSE in c.text)
+            ):
+                return True
+        return False
+
+    @classmethod
+    def _create_enriched(
+        cls,
+        original: Message,
+        turn_reminders: list[str],
+        last_words_reminders: list[str],
+    ) -> Message:
+        """Create a new ``Message`` with user contents first and reminders last.
+
+        This keeps the user's message as the first content item while leaving
+        platform context close to the end of the message.
+        """
+        reminder_contents = [wrap_system_reminder(r) for r in [*turn_reminders, *last_words_reminders]]
+        # Extract text from Content objects so Message() can rebuild them.
+        # Non-text Content (images, etc.) is passed through as-is.
+        original_items: list[Any] = []
+        for c in original.contents:
+            if c.type == "text" and c.text is not None:
+                original_items.append(escape_system_reminder_tags(c.text))
+            else:
+                original_items.append(c)
+        return cls._rebuild(original, [*original_items, *reminder_contents])
+
+    @staticmethod
+    def _rebuild(original: Message, contents: list[Any]) -> Message:
+        """A fresh wrapper for *contents* that keeps the original's identity fields.
+
+        ``additional_properties`` is shared by reference — the sanctioned
+        write-through channel for exclusion flags and the reminder record.
+        """
+        rebuilt = Message(
+            original.role,
+            contents,
+            author_name=original.author_name,
+            message_id=original.message_id,
+        )
+        rebuilt.additional_properties = original.additional_properties
+        return rebuilt