alpha-avatar-plugins-context 0.6.8__py3-none-any.whl

alphaavatar/plugins/context/history/context_history.py

@@ -0,0 +1,404 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from alphaavatar.agents.avatar.provider.enums import ModelRole
+from alphaavatar.agents.avatar.provider.errors import ModelProtocolError
+from alphaavatar.agents.avatar.provider.records import MODEL_RECORD_SCHEMA
+from alphaavatar.agents.avatar.provider.schemas import ModelInput, ModelInputMessage, ModelTextPart
+from alphaavatar.agents.avatar.provider.schemas.model_input import (
+    ModelFunctionCall,
+    ModelFunctionOutput,
+)
+from alphaavatar.core.cleanup import wait_for_cleanup
+
+if TYPE_CHECKING:
+    from alphaavatar.agents.avatar.provider.schemas.model_input import ModelInputItem
+    from alphaavatar.core.output import OutputRuntime
+    from alphaavatar.core.output.schemas import OutputRecordBatch
+    from alphaavatar.core.turn import TurnSnapshot
+
+    from ..config import ContextConfig
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class _Turn:
+    context_id: str
+    turn_id: str
+    input_id: str
+    cutoff: int
+    seed: ModelInputMessage
+    size_bytes: int
+    records: list[tuple[str | None, ModelInputItem]] = field(default_factory=list)
+    batch_digests: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def count(self) -> int:
+        return 1 + len(self.records)
+
+    def project(self) -> tuple[ModelInputItem, ...]:
+        # A retiring tool may settle after another query begins. Never expose half a pair.
+        calls = {
+            (run_id, item.call_id)
+            for run_id, item in self.records
+            if isinstance(item, ModelFunctionCall)
+        }
+        outputs = {
+            (run_id, item.call_id)
+            for run_id, item in self.records
+            if isinstance(item, ModelFunctionOutput)
+        }
+        paired = calls & outputs
+        return (
+            self.seed,
+            *(
+                item
+                for run_id, item in self.records
+                if not isinstance(item, ModelFunctionCall | ModelFunctionOutput)
+                or (run_id, item.call_id) in paired
+            ),
+        )
+
+
+class ContextHistory:
+    """Bounded canonical query history, independently acknowledging Output.records.
+
+    User inputs come from committed Turns. Assistant/tool records come only from
+    the lossless journal, not playout, LoopResult or private provider continuation.
+    Byte accounting covers serialized content, not process RSS or shared media caches.
+    """
+
+    CONSUMER_ID = "context.history"
+
+    def __init__(self, *, output: OutputRuntime, config: ContextConfig) -> None:
+        self._journal = output.records
+        self._max_turns = config.history_max_turns
+        self._max_items = config.history_max_items
+        self._max_bytes = config.history_max_bytes
+        self._turns: OrderedDict[tuple[str, str], _Turn] = OrderedDict()
+        self._bytes = self._items = self._latest_cutoff = 0
+        self._registered = self._stopping = False
+        self._worker: asyncio.Task[None] | None = None
+        self._close_task: asyncio.Task[None] | None = None
+        self._failure: Exception | None = None
+
+    def _ensure_open(self) -> None:
+        if self._close_task is not None:
+            raise RuntimeError("Context history is closing or closed")
+        if self._failure is not None:
+            raise RuntimeError("Context history consumer has failed") from self._failure
+
+    def _fail(self, error: BaseException) -> None:
+        if isinstance(error, asyncio.CancelledError):
+            failure = RuntimeError("Context history consumer cancelled without owner shutdown")
+            failure.__cause__ = error
+        elif isinstance(error, Exception):
+            failure = error
+        else:
+            raise error
+        if self._failure is None:
+            self._failure = failure
+            if self._registered:
+                self._journal.fail(self.CONSUMER_ID, failure)
+            logger.error("Context history consumer failed", exc_info=failure)
+
+    def _observe(self, task: asyncio.Task[None]) -> None:
+        if task.cancelled():
+            if not self._stopping:
+                self._fail(asyncio.CancelledError())
+        elif (error := task.exception()) is not None:
+            self._fail(error)
+
+    def _start(self) -> None:
+        self._ensure_open()
+        if not self._registered:
+            self._journal.register(self.CONSUMER_ID, required=True)
+            self._registered = True
+            self._worker = asyncio.create_task(self._run(), name=self.CONSUMER_ID)
+            self._worker.add_done_callback(self._observe)
+
+    def _evict(self, key: tuple[str, str]) -> None:
+        removed = self._turns.pop(key)
+        self._bytes -= removed.size_bytes
+        self._items -= removed.count
+
+    def _make_room(
+        self, *, target: tuple[str, str], add_bytes: int, add_items: int, add_turn: bool = False
+    ) -> bool:
+        turn = self._turns.get(target)
+        target_bytes = (turn.size_bytes if turn else 0) + add_bytes
+        target_items = (turn.count if turn else 0) + add_items
+        if target_bytes > self._max_bytes or target_items > self._max_items:
+            raise RuntimeError("A single turn exceeds canonical context history capacity")
+
+        victims = []
+        size = self._bytes + add_bytes
+        count = self._items + add_items
+        turns = len(self._turns) + int(add_turn)
+        for key, value in self._turns.items():
+            if size <= self._max_bytes and count <= self._max_items and turns <= self._max_turns:
+                break
+
+            # Whole-turn eviction never leaves an orphan tool record in the projected input.
+            if key == target:
+                if key == next(reversed(self._turns)):
+                    raise RuntimeError("The current turn cannot fit in context history")
+
+                victims.append(key)
+                break
+
+            victims.append(key)
+            size, count, turns = size - value.size_bytes, count - value.count, turns - 1
+
+        for key in victims:
+            self._evict(key)
+
+        return target not in victims
+
+    def _ingest(self, batch: OutputRecordBatch) -> None:
+        if batch.schema != MODEL_RECORD_SCHEMA:
+            return
+
+        key = batch.scope.context_id, batch.scope.turn_id
+        turn = self._turns.get(key)
+        if turn is None:
+            # A late result stays in canonical storage; it cannot resurrect an evicted query.
+            return
+
+        previous = turn.batch_digests.get(batch.batch_id)
+        if previous is not None:
+            if previous != batch.digest:
+                raise ModelProtocolError("Conflicting canonical batch replay")
+            return
+
+        if not batch.items or type(batch.size_bytes) is not int or batch.size_bytes < 1:
+            raise ModelProtocolError("Canonical history requires a nonempty measured batch")
+
+        existing = {
+            item.id
+            for value in self._turns.values()
+            if value.context_id == turn.context_id
+            for item in (value.seed, *(item for _, item in value.records))
+        }
+        run_id = batch.scope.run_id
+        if not isinstance(run_id, str) or not run_id:
+            raise ModelProtocolError("Canonical model records require their owning run")
+
+        calls = {
+            (owner, item.call_id): item
+            for owner, item in turn.records
+            if isinstance(item, ModelFunctionCall)
+        }
+        output_ids = {
+            (owner, item.call_id)
+            for owner, item in turn.records
+            if isinstance(item, ModelFunctionOutput)
+        }
+        records = []
+        for item in batch.items:
+            if item.id in existing:
+                raise ModelProtocolError("Canonical model item identity was reused")
+
+            existing.add(item.id)
+            if isinstance(item, ModelInputMessage):
+                if item.role != ModelRole.ASSISTANT:
+                    raise ModelProtocolError(
+                        "Output history cannot contain user or policy messages"
+                    )
+            elif isinstance(item, ModelFunctionCall):
+                if (run_id, item.call_id) in calls:
+                    raise ModelProtocolError("Canonical tool call identity was reused")
+                calls[run_id, item.call_id] = item
+            elif isinstance(item, ModelFunctionOutput):
+                call = calls.get((run_id, item.call_id))
+                if call is None or call.name != item.name or (run_id, item.call_id) in output_ids:
+                    raise ModelProtocolError("Canonical tool output has no unique owning call")
+                output_ids.add((run_id, item.call_id))
+            else:
+                raise ModelProtocolError("Private continuation cannot enter canonical history")
+
+            records.append((run_id, item))
+
+        if not self._make_room(target=key, add_bytes=batch.size_bytes, add_items=len(records)):
+            return
+
+        turn.records.extend(records)
+        turn.batch_digests[batch.batch_id] = batch.digest
+        turn.size_bytes += batch.size_bytes
+        self._bytes, self._items = self._bytes + batch.size_bytes, self._items + len(records)
+
+    def drain(self) -> None:
+        if not self._registered:
+            return
+
+        if self._failure is not None:
+            raise RuntimeError("Context history consumer failed") from self._failure
+
+        try:
+            while True:
+                read = self._journal.read_pending(consumer_id=self.CONSUMER_ID)
+                if read.has_gap:
+                    raise RuntimeError("Context history missed canonical records")
+
+                for event in read.items:
+                    if event.scope != event.payload.scope:
+                        raise ModelProtocolError("Canonical batch scope changed")
+
+                    self._ingest(event.payload)
+                    self._journal.commit(consumer_id=self.CONSUMER_ID, cursor_seq=event.sequence)
+
+                if read.cursor_seq >= read.latest_seq:
+                    return
+        except BaseException as error:
+            self._fail(error)
+            raise
+
+    def accept_turn(self, snapshot: TurnSnapshot, context_id: str) -> ModelInput:
+        self._start()
+        key = context_id, snapshot.turn_id
+        previous = self._turns.get(key)
+        if previous is not None:
+            if (previous.input_id, previous.cutoff) != (
+                snapshot.input_id,
+                snapshot.cutoff.sequence,
+            ):
+                raise ModelProtocolError("Committed turn identity changed")
+
+            return ModelInput(items=(previous.seed,))
+
+        if snapshot.cutoff.sequence < self._latest_cutoff:
+            raise RuntimeError("This committed input is outside the retained context history")
+
+        metadata = MappingProxyType(
+            {
+                "context_id": context_id,
+                "turn_id": snapshot.turn_id,
+                "input_modality": snapshot.modality.value,
+            }
+        )
+        text = (
+            snapshot.text
+            if snapshot.text is not None
+            else (
+                '<historical_media omitted="true" current="false">'
+                "Visual input belongs to this earlier turn; do not infer its contents from this placeholder."
+                "</historical_media>"
+            )
+        )
+        seed = ModelInputMessage(
+            id=snapshot.input_id,
+            role=ModelRole.USER,
+            parts=(ModelTextPart(text),),
+            created_at=snapshot.committed_at.unix_seconds,
+            metadata=metadata,
+        )
+        size = len(
+            json.dumps(
+                {
+                    "id": seed.id,
+                    "text": text,
+                    "metadata": dict(metadata),
+                    "created_at": seed.created_at,
+                },
+                ensure_ascii=False,
+                allow_nan=False,
+            ).encode()
+        )
+
+        if any(
+            value.context_id == context_id
+            and (value.input_id == seed.id or any(item.id == seed.id for _, item in value.records))
+            for value in self._turns.values()
+        ):
+            raise ModelProtocolError("Context input identity was reused")
+
+        self._make_room(target=key, add_bytes=size, add_items=1, add_turn=True)
+        self._turns[key] = _Turn(
+            context_id, snapshot.turn_id, snapshot.input_id, snapshot.cutoff.sequence, seed, size
+        )
+        self._bytes, self._items = self._bytes + size, self._items + 1
+        self._latest_cutoff = max(self._latest_cutoff, snapshot.cutoff.sequence)
+        return ModelInput(items=(seed,))
+
+    def capture(self, snapshot: TurnSnapshot, context_id: str, current: ModelInput) -> ModelInput:
+        self._ensure_open()
+        if (
+            len(current.items) != 1
+            or not isinstance(current.items[0], ModelInputMessage)
+            or (current.items[0].id != snapshot.input_id or current.items[0].role != ModelRole.USER)
+        ):
+            raise ValueError(
+                "Context preparation requires exactly the current committed input seed"
+            )
+
+        self.drain()
+        key = context_id, snapshot.turn_id
+        if key not in self._turns:
+            raise RuntimeError("Current turn is not retained in context history")
+        if current.realtime is not None or current.items != (self._turns[key].seed,):
+            raise ValueError("Current input differs from its canonical committed Turn seed")
+
+        items = []
+        for entry_key, turn in self._turns.items():
+            if entry_key == key:
+                items.extend(current.items)
+                break
+            if turn.context_id == context_id:
+                items.extend(turn.project())
+
+        ids = [item.id for item in items]
+        call_ids = [item.call_id for item in items if isinstance(item, ModelFunctionCall)]
+        if len(ids) != len(set(ids)) or len(call_ids) != len(set(call_ids)):
+            raise ModelProtocolError("Captured canonical history has duplicate identities")
+
+        return ModelInput(items=tuple(items))
+
+    async def _run(self) -> None:
+        while await self._journal.wait_for_pending(consumer_id=self.CONSUMER_ID):
+            self.drain()
+
+    async def _close(self) -> None:
+        errors = []
+        try:
+            self.drain()
+        except Exception as error:
+            errors.append(error)
+        if self._worker is not None:
+            if not self._worker.done() and not self._worker.cancelling():
+                self._stopping = True
+                self._worker.cancel()
+            await asyncio.gather(self._worker, return_exceptions=True)
+            self._observe(self._worker)
+        if self._registered and self._failure is None:
+            self._journal.unregister(self.CONSUMER_ID)
+            self._registered = False
+        if self._failure is not None and self._failure not in errors:
+            errors.append(self._failure)
+        if errors:
+            raise ExceptionGroup("Context history cleanup failed", errors)
+
+    async def aclose(self) -> None:
+        if self._close_task is None:
+            self._close_task = asyncio.create_task(self._close(), name="context_history_close")
+        await wait_for_cleanup(self._close_task)

alphaavatar/plugins/context/manager.py

@@ -0,0 +1,282 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any
+
+from alphaavatar.agents.avatar.context import ContextManager
+from alphaavatar.agents.avatar.context.schemas import ContextBuildRequest, ContextPrepareRequest
+from alphaavatar.agents.avatar.provider.enums import ModelInputType
+from alphaavatar.agents.avatar.provider.errors import ModelProtocolError
+from alphaavatar.agents.avatar.provider.schemas import ModelInput
+from alphaavatar.agents.avatar.provider.schemas.model_input import ModelInputItem
+from alphaavatar.agents.avatar.vision import VisualFrameSelector
+from alphaavatar.agents.constants import DEFAULT_SYSTEM_VALUE
+from alphaavatar.agents.utils.time import ParticipantTimeContext, format_user_time
+from alphaavatar.core.cleanup import wait_for_cleanup
+from alphaavatar.core.env.enums import ObservationKind
+from alphaavatar.core.perception import PerceptionTemporalAligner, TemporalAlignmentMode
+from alphaavatar.core.time import RuntimeTimeRange
+
+from .builder import ContextBuilder
+from .config import ContextConfig
+from .history import ContextHistory
+from .snapshot import snapshot_input
+from .template import AvatarSysPromptTemplate, RuntimeStateTemplate
+
+if TYPE_CHECKING:
+    from alphaavatar.agents.configs import AvatarConfig
+    from alphaavatar.agents.memory import MemoryBase
+    from alphaavatar.agents.persona import PersonaBase
+    from alphaavatar.agents.runtime import AvatarRuntime, StateRuntime
+    from alphaavatar.core.turn import TurnSnapshot
+
+logger = logging.getLogger(__name__)
+
+
+class AvatarContextManager(ContextManager):
+    """Own canonical query history and snapshots, not execution handles or SDK state."""
+
+    _OBSERVATION_KINDS = frozenset(
+        {
+            ObservationKind.VIDEO_FRAME,
+            ObservationKind.SCREEN_FRAME,
+            ObservationKind.SPEECH_SEGMENT,
+            ObservationKind.TRANSCRIPT_SEGMENT,
+            ObservationKind.TEXT_INPUT,
+            ObservationKind.IMAGE_INPUT,
+        }
+    )
+
+    def __init__(
+        self, *, runtime: AvatarRuntime, avatar_config: AvatarConfig, config: ContextConfig
+    ) -> None:
+        self._runtime = runtime
+        self._config = config
+        self._vision = avatar_config.vision.model_copy(deep=True)
+        self._alignment_policy = avatar_config.runtime.perception.temporal_alignment.build_policy()
+        self._introduction = avatar_config.avatar.introduction
+        self._memory: MemoryBase | None = None
+        self._persona: PersonaBase | None = None
+        self._history = ContextHistory(output=runtime.output, config=config)
+        self._pending = 0
+        self._work: set[asyncio.Task[ModelInput]] = set()
+        self._close_task: asyncio.Task[None] | None = None
+
+    @property
+    def initial_instructions(self) -> str:
+        self._ensure_open()
+        persona = self._persona.persona_content if self._persona is not None else None
+        return self._system_template(self._runtime.state).instructions(
+            stable_persona=persona or self._runtime.state.user_persona or DEFAULT_SYSTEM_VALUE
+        )
+
+    @staticmethod
+    def _observe(task: asyncio.Task[Any]) -> None:
+        if not task.cancelled():
+            task.exception()
+
+    def _ensure_open(self) -> None:
+        if self._close_task is not None:
+            raise RuntimeError("Context manager is closing or closed")
+
+    def bind_sources(self, *, memory: MemoryBase, persona: PersonaBase) -> None:
+        self._ensure_open()
+        different = self._memory is not memory or self._persona is not persona
+        if self._memory is not None and different:
+            raise RuntimeError("Context sources are already bound to another Engine")
+        if self._pending or self._work:
+            raise RuntimeError("Cannot bind Context sources during preparation")
+        self._memory, self._persona = memory, persona
+
+    def accept_turn(self, snapshot: TurnSnapshot) -> ModelInput:
+        self._ensure_open()
+        context_id = self._runtime.state.context_id
+        if self._runtime.turn.get(snapshot.input_id) is not snapshot:
+            raise ValueError("Context can only accept a Turn owned by this runtime")
+        if context_id not in snapshot.context_ids:
+            raise ValueError("Committed input belongs to another context")
+        return self._history.accept_turn(snapshot, context_id)
+
+    def _system_template(self, state: StateRuntime) -> AvatarSysPromptTemplate:
+        return AvatarSysPromptTemplate(
+            self._introduction,
+            interaction_method=state.interaction_method,
+            internal_capabilities=self._runtime.capability_registry.capabilities,
+            stable_behavior_rules=self._config.behavior_rules,
+        )
+
+    def _state_snapshot(self) -> StateRuntime:
+        state = self._runtime.state
+        times = {}
+        for identity, participant in self._runtime.session.participants.items():
+            time = format_user_time(
+                participant.user_time.timezone, participant.user_time.timezone_source
+            )
+            times[identity] = ParticipantTimeContext(
+                participant_id=identity, user_id=participant.effective_user_id, user_time=time
+            )
+
+        # Read sources once. Preparing a query must not write to shared State or participants.
+        memory = self._memory.memory_content if self._memory is not None else state.memory_content
+        persona = self._persona.persona_content if self._persona is not None else state.user_persona
+        return replace(
+            state,
+            participant_time=times,
+            interaction_method=replace(
+                state.interaction_method, notes=list(state.interaction_method.notes)
+            ),
+            memory_content=memory or DEFAULT_SYSTEM_VALUE,
+            user_persona=persona or DEFAULT_SYSTEM_VALUE,
+            turn_behavior_rules="\n".join((state.global_behavior_rules, state.turn_behavior_rules)),
+        )
+
+    def _compose(
+        self,
+        request: ContextPrepareRequest,
+        snapshot: TurnSnapshot,
+        system_prompt: str,
+        runtime_context: str,
+    ) -> ModelInput:
+        events = snapshot.perception_events
+        if self._vision.input_mode != ModelInputType.REALTIME:
+            events = tuple(
+                event
+                for event in events
+                if event.source_state is not None
+                or (
+                    event.observation is not None
+                    and event.observation.kind in self._OBSERVATION_KINDS
+                )
+            )
+
+        # Request-local helpers avoid races between concurrent preparation workers.
+        alignment = PerceptionTemporalAligner(self._alignment_policy).align(
+            events=events,
+            time_range=RuntimeTimeRange(start=snapshot.started_at, end=snapshot.committed_at),
+            source_states_at_start=snapshot.source_states_at_start,
+            source_states_at_end=snapshot.source_states_at_commit,
+            has_event_gap=snapshot.perception_gap,
+            missed_event_count=snapshot.missed_perception_events,
+            mode=TemporalAlignmentMode.FIXED
+            if self._vision.input_mode == ModelInputType.REALTIME
+            else None,
+        )
+        selection = VisualFrameSelector().select(alignment=alignment, config=self._vision)
+        result = ContextBuilder().build(
+            request=ContextBuildRequest(
+                base_input=request.input,
+                input_id=request.input_id,
+                alignment=alignment,
+                visual_selection=selection,
+                model_input_type=self._vision.input_mode,
+            ),
+            system_prompt=system_prompt,
+            runtime_context=runtime_context,
+            contributions=request.contributions,
+            query_scope=f"{request.context_id}:{request.turn_id}",
+        )
+
+        return snapshot_input(result.model_input)
+
+    async def prepare(self, request: ContextPrepareRequest) -> ModelInput:
+        self._ensure_open()
+        if not isinstance(request, ContextPrepareRequest):
+            raise TypeError("ContextManager requires ContextPrepareRequest")
+
+        if self._pending + len(self._work) >= self._config.max_pending_preparations:
+            raise RuntimeError("Context preparation capacity exhausted")
+
+        self._pending += 1
+        reserved = True
+        try:
+            request = replace(request, input=snapshot_input(request.input))
+            snapshot = self._runtime.turn.get(request.input_id)
+            if snapshot is None or snapshot.turn_id != request.turn_id:
+                raise ValueError("Context input does not identify the requested committed turn")
+            if (
+                request.context_id not in snapshot.context_ids
+                or request.context_id != self._runtime.state.context_id
+            ):
+                raise ValueError("Committed turn does not belong to the requested context")
+
+            # Standalone native Loop callers use the same acceptance path as the Engine.
+            self.accept_turn(snapshot)
+            ready = await self._runtime.turn.wait_context_ready(snapshot)
+            self._ensure_open()
+            if request.context_id != self._runtime.state.context_id:
+                raise ValueError("State no longer belongs to the requested context")
+            if not ready:
+                logger.debug("Context readiness timed out turn_id=%s", request.turn_id)
+
+            request = replace(
+                request, input=self._history.capture(snapshot, request.context_id, request.input)
+            )
+            state = self._state_snapshot()
+            system = self._system_template(state).instructions(stable_persona=state.user_persona)
+            text = RuntimeStateTemplate().render(state_runtime=state)
+            task = asyncio.create_task(
+                asyncio.to_thread(self._compose, request, snapshot, system, text),
+                name=f"context_prepare:{request.turn_id}",
+            )
+            self._work.add(task)
+            self._pending -= 1
+            reserved = False
+            task.add_done_callback(self._work.discard)
+            task.add_done_callback(self._observe)
+
+            # Cancellation drops this request's delivery, not ownership of an in-flight worker.
+            result = await asyncio.shield(task)
+            self._ensure_open()
+            return result
+        finally:
+            if reserved:
+                self._pending -= 1
+
+    def build(
+        self, prefix: ModelInput, *, continuation: tuple[ModelInputItem, ...] = ()
+    ) -> ModelInput:
+        self._ensure_open()
+        if not isinstance(prefix, ModelInput):
+            raise TypeError("ContextManager requires a captured ModelInput")
+
+        identities = {item.id for item in prefix.items}
+        added = {item.id for item in continuation}
+
+        if len(identities) != len(prefix.items) or len(added) != len(continuation):
+            raise ModelProtocolError("Context contains duplicate item identities")
+
+        if identities.intersection(added):
+            raise ModelProtocolError("Context continuation overlaps its captured prefix")
+
+        if any(ContextBuilder._is_runtime_context_item(item) for item in continuation):
+            raise ModelProtocolError("Runtime context is not canonical execution history")
+
+        return replace(prefix, items=(*prefix.items, *continuation))
+
+    async def _close(self) -> None:
+        await asyncio.gather(*tuple(self._work), return_exceptions=True)
+        self._work.clear()
+        try:
+            await self._history.aclose()
+        finally:
+            self._memory = self._persona = None
+
+    async def aclose(self) -> None:
+        if self._close_task is None:
+            self._close_task = asyncio.create_task(self._close(), name="context_manager_close")
+        await wait_for_cleanup(self._close_task)