> ## Documentation Index > Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt > Use this file to discover all available pages before exploring further. # Runtime Patches > The internal ContextMutation types used to patch the base transcript at compile boundaries # Runtime Patches `ContextMutation` is SimpleLLMFunc's internal typed patch protocol for transcript edits produced by runtime side effects. Mutations do **not** define the whole context. The final LLM request is compiled from: 1. invocation configuration — docstring prompt, template parameters, tool guidance, output contract, SelfRef snapshot; 2. a base transcript/message list — history, current user input, previous assistant/tool messages; 3. runtime patches — the `ContextMutation` objects described on this page. Understanding mutations is useful when debugging framework internals, but application code usually interacts with higher-level surfaces such as tools, event streams, `history`, and SelfRef primitives. ## The Mutation Union ```python theme={null} ContextMutation = Union[ AssistantMessageMutation, ToolResultMutation, MultimodalToolResultMutation, UserMessageMutation, ContextReplaceMutation, ContextSummaryMutation, ExperienceRememberMutation, ExperienceForgetMutation, AssistantTruncatedMutation, ToolCancelledMutation, ] ``` ## Standard Flow Patches These are produced during normal ReAct loop operation. ### AssistantMessageMutation Emitted when the LLM produces a response (text, tool calls, or both). ```python theme={null} @dataclass class AssistantMessageMutation: role: Literal["assistant"] = "assistant" content: Optional[str] = None tool_calls: List[Dict[str, Any]] = field(default_factory=list) reasoning_details: List[Dict[str, Any]] = field(default_factory=list) ``` **When:** After every successful LLM call.\ **Effect:** Appends an assistant message to the transcript.\ **Producer:** `execute_single_llm_phase()` in the ReAct loop. ### ToolResultMutation Emitted when a tool finishes execution with a text result. ```python theme={null} @dataclass class ToolResultMutation: tool_call_id: str content: str role: Literal["tool"] = "tool" ``` **When:** After each tool in a batch completes.\ **Effect:** Appends a tool result message linked to its call by `tool_call_id`.\ **Producer:** `schedule_tool_batch()` → tool execution. ### MultimodalToolResultMutation Emitted when a tool returns images or mixed content that can't be represented as a simple string. ```python theme={null} @dataclass class MultimodalToolResultMutation: tool_call_id: str tool_name: str arguments: str user_messages: List[Dict[str, Any]] ``` **When:** Tool returns `ImgPath`, `ImgUrl`, or a tuple containing multimodal content.\ **Effect:** Replaces the tool call with an assistant summary message + user messages containing the multimodal content. This restructuring is required because most providers only support images in user messages.\ **Producer:** `schedule_tool_batch()` with multimodal tool returns. ### UserMessageMutation Emitted when a new user message needs to be injected mid-loop. ```python theme={null} @dataclass class UserMessageMutation: message: Dict[str, Any] ``` **When:** Rare in normal flow. Used by input routing (e.g., TUI tool-input) or custom hooks.\ **Effect:** Appends a user message to the transcript.\ **Producer:** Custom hooks, `AgentInputRouter`. ## Context Reset Patches These replace or restructure the working transcript. ### ContextReplaceMutation Hard reset — replaces the entire message list. ```python theme={null} @dataclass class ContextReplaceMutation: messages: List[Dict[str, Any]] ``` **When:** External history override, fork context injection.\ **Effect:** Discards the current transcript entirely, replaces with `messages`.\ **Producer:** SelfRef fork spawn (to set child context), custom hooks. ### ContextSummaryMutation Context compaction — replaces transcript with a summary and optionally stores new experiences. ```python theme={null} @dataclass class ContextSummaryMutation: summary_message: Dict[str, Any] remember: List[Dict[str, str]] = field(default_factory=list) ``` **When:** `runtime.selfref.context.compact(...)` is called from a tool.\ **Effect:** 1. Preserves the system prompt message 2. Replaces the working transcript with `summary_message` 3. Stores any items in `remember` as durable experiences **Producer:** SelfRef `compact` primitive. ## Experience Patches These update durable experiences stored in the system context (via SelfRef). ### ExperienceRememberMutation Store a new durable experience. ```python theme={null} @dataclass class ExperienceRememberMutation: text: str ``` **When:** `runtime.selfref.context.remember(...)` is called.\ **Effect:** Adds the text as a new experience entry in the system context's experience section.\ **Producer:** SelfRef `remember` primitive. ### ExperienceForgetMutation Remove a stored experience by ID. ```python theme={null} @dataclass class ExperienceForgetMutation: experience_id: str ``` **When:** `runtime.selfref.context.forget(...)` is called.\ **Effect:** Removes the experience with the matching ID from the system context.\ **Producer:** SelfRef `forget` primitive. ## Abort Patches These handle interruption and cancellation. ### AssistantTruncatedMutation Records a partially-received assistant response that was interrupted. ```python theme={null} @dataclass class AssistantTruncatedMutation: partial_content: str abort_reason: str = "" ``` **When:** `AbortSignal` fires while the LLM is streaming.\ **Effect:** Appends the partial content as an assistant message with truncation metadata.\ **Producer:** `execute_single_llm_phase()` on abort. ### ToolCancelledMutation Records a tool call that was aborted before completion. ```python theme={null} @dataclass class ToolCancelledMutation: tool_call_id: str tool_name: str abort_reason: str = "" ``` **When:** `AbortSignal` fires while tools are executing.\ **Effect:** Appends a cancelled-tool result message so the transcript remains structurally valid (every tool call has a corresponding result).\ **Producer:** `schedule_tool_batch()` on abort. ## Mutation Application Order Mutations are applied sequentially in the order they were produced. Within a single ReAct iteration: 1. **Hook mutations** (from SelfRef session `collect_context_mutations`) — applied first 2. **LLM mutations** (AssistantMessage) — from the LLM call 3. **Tool mutations** (ToolResult, MultimodalToolResult, Experience\*) — from tool execution 4. **Abort mutations** (AssistantTruncated, ToolCancelled) — if interruption occurred Experience mutations (Remember/Forget) are accumulated and committed as a batch before the next non-experience mutation is applied. This ensures experiences are stored before any context replacement that might reference them. ## The Guarantee Runtime-produced transcript edits go through this patch protocol. This means LLM calls, tool execution, SelfRef primitives, and abort handling do not directly mutate the live transcript. This does **not** mean every LLM-visible input comes from a mutation. The initial transcript, docstring/system prompt, template parameters, tool guidance, and SelfRef snapshot are separate compile inputs. How invocation config, transcript, and runtime patches are transformed into the final LLM request.