agentengine-sdk-python 0.8.5__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/harness/engine/context_pipeline.py

@@ -7,16 +7,26 @@
 
 from __future__ import annotations
 
+import asyncio
+import hashlib
+import json
+import re
 from typing import Any, Callable
 
-from ksadk.harness.compaction_record import build_compaction_record
+from ksadk.harness.compaction_record import CompactionRecord, build_compaction_record
+from ksadk.harness.context_sections import BUILTIN_CONTRIBUTORS, sections_to_context_items
 from ksadk.harness.events import EventType, RuntimeEvent
+from ksadk.harness.hooks import RunContext, run_hooks
 from ksadk.harness.loop import ModelFailoverExhausted, ReasonInput, reason_turn_async
+from ksadk.harness.multimodal import runtime_input_text
 from ksadk.harness.state import Message, MessageRole
 
 #: 事件构造函数签名（引擎的 _event）。
 EventFn = Callable[..., RuntimeEvent]
 
+#: G12 §15.2：摘要输出命中敏感策略时的占位文本。
+_REDACTED_SUMMARY_PLACEHOLDER = "[摘要降级为占位：摘要输出命中敏感数据策略，原文不进入 Context]"
+
 
 class EngineContextPipeline:
     """ContextEngine 的运行时编排：规划、压缩、组装、Manifest 投影。"""
@@ -29,12 +39,21 @@ class EngineContextPipeline:
         event_fn: EventFn,
         memory_runtime: Any | None = None,
         prompt_cache_tracker: Any | None = None,
+        context_contributors: tuple[Any, ...] = (),
+        sensitive_policy: Any | None = None,
+        hooks: tuple[Any, ...] = (),
     ) -> None:
         self._context_engine = context_engine
         self._reasoner = reasoner
         self._event = event_fn
         self._memory_runtime = memory_runtime
         self._prompt_cache_tracker = prompt_cache_tracker
+        # Compile 期固化（引擎构造时冻结，Runtime 期只读，与 hooks 纪律一致）。
+        self._context_contributors = tuple(context_contributors)
+        # G12：与 MCP Offload 同源的敏感数据策略（sensitive_match/sensitive_patterns）。
+        self._sensitive_policy = sensitive_policy
+        # G5：Provider 级扩展拦截面（on_context 等四钩子），构造期固化、只读。
+        self._hooks = tuple(hooks)
 
     # ------------------------------------------------------------ 主入口
 
@@ -58,7 +77,13 @@ class EngineContextPipeline:
             for m in history
             if isinstance(m, dict) and m.get("role") in {"user", "assistant", "system"}
         ]
-        current_input = str(run.request.input or "")
+        # 回放路径 tool 消息被整体过滤（上方角色白名单），原 assistant
+        # tool_calls 载体退化为空文本 assistant——纯噪音（G15.1 观察项），
+        # 且无正文可保留，直接剔除。
+        messages = [
+            m for m in messages if not (m.role is MessageRole.ASSISTANT and not m.content.strip())
+        ]
+        current_input = runtime_input_text(run.request.input)
         # Studio/Draft 会把本轮输入同时放进 request.input 和历史末尾。历史副本
         # 不能继续作为可丢弃 history_round 参与规划，否则超大本轮输入会在
         # Planner 限额时被静默裁掉。只移除重复副本，本轮输入始终以 required
@@ -79,12 +104,36 @@ class EngineContextPipeline:
         policy = run.compiled.spec.context_policy
         max_input = plan.budget.max_input_tokens
 
-        if plan.planned_input_tokens > int(policy.proactive_compaction_threshold * max_input) or (
-            # Planner 丢弃了历史轮次（静默丢上下文）→ 主动压缩以摘要保住事实。
-            any(d.action == "dropped" and d.item_id.startswith("history") for d in plan.decisions)
+        if (
+            plan.planned_input_tokens > int(policy.proactive_compaction_threshold * max_input)
+            or (
+                # G18 ② 预测式触发：在 proactive_threshold 之前提前压缩。
+                # 复用 proactive 路径，不新增档位；
+                # trigger 仍记 "proactive" 保持事件契约稳定，以 trigger_reason 区分预测式与主动式）
+                plan.planned_input_tokens > int(policy.predictive_compaction_ratio * max_input)
+            )
+            or (
+                # Planner 丢弃了历史轮次（静默丢上下文）→ 主动压缩以摘要保住事实。
+                any(
+                    d.action == "dropped" and d.item_id.startswith("history")
+                    for d in plan.decisions
+                )
+            )
         ):
+            trigger_reason = (
+                "predictive"
+                if plan.planned_input_tokens
+                <= int(policy.proactive_compaction_threshold * max_input)
+                else "proactive"
+            )
             compacted = await self._compact_history(
-                run, messages, trigger="proactive", keep_recent=6, budget_tokens=max_input
+                run,
+                messages,
+                trigger="proactive",
+                keep_recent=6,
+                budget_tokens=max_input,
+                keep_recent_tokens=int(policy.keep_recent_token_ratio * max_input),
+                trigger_reason=trigger_reason,
             )
             if compacted is not None:
                 messages = compacted
@@ -95,7 +144,12 @@ class EngineContextPipeline:
         if plan.planned_input_tokens > max_input:
             # 紧急压缩（§8.4）：更强压缩，只允许一次。
             compacted = await self._compact_history(
-                run, messages, trigger="emergency", keep_recent=2, budget_tokens=max_input
+                run,
+                messages,
+                trigger="emergency",
+                keep_recent=2,
+                budget_tokens=max_input,
+                keep_recent_tokens=int(policy.keep_recent_token_ratio * max_input),
             )
             if compacted is not None:
                 messages = compacted
@@ -120,11 +174,171 @@ class EngineContextPipeline:
         assembled = self._context_engine.assemble_chat(plan)
         if not assembled.messages or assembled.messages[0].get("role") != "system":
             assembled.messages.insert(0, {"role": "system", "content": instructions})
+        # G5 §5.2：on_context 在组装后、Manifest 投影前拦截首次模型输入（语义见下）。
+        messages_out = list(assembled.messages)
+        projected = _projected_tokens(messages_out)
+        messages_out, projected = await self._apply_on_context_hooks(
+            run, plan, messages_out, projected, window
+        )
         # 长任务方案 §6.2：Manifest 可观测快照 + context.built（Planned/Projected；
         # Actual 由 usage 回填）。正文不入 Manifest，只记 Hash/引用/Token。
-        projected = sum(count_tokens(str(m.get("content") or "")) for m in assembled.messages)
         self._emit_context_built(run, plan, projected, window)
-        return assembled.messages
+        return messages_out
+
+    async def prepare_turn_context(
+        self,
+        run: Any,
+        messages: list[dict[str, Any]],
+        instructions: str,
+        tools: list[Any] | tuple[Any, ...],
+    ) -> list[dict[str, Any]]:
+        """在每个后续模型回合前重新核算并按需压缩真实输入。
+
+        首轮 ``prepare_context`` 只负责把会话历史装配进图状态。长任务随后会不断
+        追加 assistant/tool 消息；如果后续回合不再经过预算闸门，ContextEngine
+        实际只在首轮生效。这里以 Provider 真正收到的 ``messages + tools`` 为口径
+        做预测式压缩，并保留未被压缩尾部的原始 OpenAI 消息（尤其是完整
+        ``tool_calls`` / ``tool_call_id``），避免为了压缩破坏工具调用配对。
+        """
+
+        if not messages:
+            return messages
+        window, source = self._resolve_window(run)
+        build_budget = getattr(self._context_engine, "build_budget", None)
+        if not callable(build_budget):
+            # ContextEngine 的旧兼容实现只提供 plan/assemble_chat。逐轮预算核算是
+            # 增量能力，不能让这类实现（以及第三方 adapter）在第二个模型回合
+            # 直接崩溃；它们仍保留首轮 plan 的既有行为。
+            return messages
+        budget = build_budget(run.compiled.spec, context_window_tokens=window)
+        max_input = budget.max_input_tokens
+        tool_schema_tokens = _tool_schema_tokens(tools)
+        projected = _projected_tokens(messages) + tool_schema_tokens
+        policy = run.compiled.spec.context_policy
+        trigger_at = int(policy.predictive_compaction_ratio * max_input)
+        if projected <= trigger_at:
+            return messages
+
+        stable_prefix: list[dict[str, Any]] = []
+        dynamic_messages = list(messages)
+        if messages and str(messages[0].get("role") or "") == "system":
+            stable_prefix = [dict(messages[0])]
+            dynamic_messages = list(messages[1:])
+        converted = [_chat_message(message) for message in dynamic_messages]
+        # 少量消息无法形成有意义的 head/tail；工具 schema 本身过大也不能靠
+        # 摘要解决。此时保持原输入，避免每轮重复生成无效摘要。
+        if len(converted) <= 6:
+            return messages
+
+        available_for_messages = max(1024, max_input - tool_schema_tokens)
+        keep_recent_tokens = max(512, int(policy.keep_recent_token_ratio * available_for_messages))
+        compacted = await self._compact_history(
+            run,
+            converted,
+            trigger="proactive",
+            keep_recent=6,
+            budget_tokens=available_for_messages,
+            keep_recent_tokens=keep_recent_tokens,
+            trigger_reason="predictive_turn",
+        )
+        if compacted is None:
+            return messages
+
+        # _compact_history 的第一条是新摘要，后面是原 converted 尾部。模型输入
+        # 必须换回原始 dict 尾部，才能保住 assistant.tool_calls 等结构字段。
+        tail_count = max(0, len(compacted) - 1)
+        rebuilt = list(stable_prefix)
+        rebuilt.append({"role": "system", "content": compacted[0].content})
+        if tail_count:
+            tail = [dict(message) for message in dynamic_messages[-tail_count:]]
+            # Some OpenAI-compatible gateways reject a compacted transcript
+            # whose first non-system message is an assistant tool-call, even
+            # when its following tool results are perfectly paired. Replay the
+            # actual current request here: a generic "continue" user message
+            # made a short Skill question turn into an unrelated older task.
+            if str(tail[0].get("role") or "") == "assistant":
+                current_request = runtime_input_text(run.request.input).strip()
+                rebuilt.append(
+                    {
+                        "role": "user",
+                        "content": current_request
+                        or "【运行时衔接占位，非用户新指令】请只处理本轮已记录的请求。",
+                    }
+                )
+            rebuilt.extend(tail)
+
+        projected_after = _projected_tokens(rebuilt) + tool_schema_tokens
+        plan = self._plan_context(
+            run,
+            [_chat_message(message) for message in rebuilt[len(stable_prefix) :]],
+            current_input="",
+        )
+        self._emit_planned(
+            run,
+            plan,
+            window,
+            source,
+            planned_input_tokens=projected_after,
+            tool_schema_tokens=tool_schema_tokens,
+        )
+        self._emit_context_built(
+            run,
+            plan,
+            projected_after,
+            window,
+            tool_schema_tokens=tool_schema_tokens,
+        )
+        return rebuilt
+
+    # ------------------------------------------------------------ Provider 钩子
+
+    def _hook_event(self, run: Any) -> Callable[..., None]:
+        """钩子的降级上报通道：复用引擎 ``_event`` 信封与 seq 单调。"""
+
+        def _emit(_hook_run: Any, event_type: str, payload: dict[str, Any]) -> None:
+            run.events.append(self._event(run, event_type, payload))
+
+        return _emit
+
+    async def _apply_on_context_hooks(
+        self, run: Any, plan: Any, messages: list[dict[str, Any]], projected: int, window: int
+    ) -> tuple[list[dict[str, Any]], int]:
+        """on_context 拦截待发 Provider 的模型输入（prepare_context / recover 共用）。
+
+        Option B：钩子改写时先按改写前输入落一代 context.built，再按改写后输入追投
+        一代（supersedes 链指向初跑世代）；仅 projected_tokens 反映改写后规模，
+        sections/content_hash/planned_tokens 保持改写前记账（投影语义，非事实源）。
+        改写回合 PROMPT_CACHE_DIAGNOSTIC 双跑属预期（两代同属一次构建，与 G13
+        断言语义一致）。返回非 list 属协议违约 → 可见降级、沿用原输入，不抛错。
+        """
+        if not self._hooks:
+            return messages, projected
+        hooked = await run_hooks(
+            self._hooks,
+            "on_context",
+            _run_context_of(run),
+            self._hook_event(run),
+            # 逐条 dict 拷贝：就地改写的钩子作用于副本，`!=` 才能检出。
+            payload={"messages": [dict(m) for m in messages]},
+        )
+        if not isinstance(hooked, list):
+            # run_hooks 链式守卫下不可达；纵深防御。（降级落账后沿用原输入）
+            self._hook_event(run)(
+                None,
+                EventType.POLICY_DECISION,
+                {
+                    "action": "hook_failed",
+                    "reason": "on_context returned non-list",
+                    "outcome": "hook_failed",
+                    "method": "on_context",
+                    "error": f"on_context 返回 {type(hooked).__name__}，期望 list[dict]",
+                },
+            )
+            return messages, projected
+        if hooked == messages:
+            return messages, projected
+        self._emit_context_built(run, plan, projected, window)
+        return hooked, _projected_tokens(hooked)
 
     async def recover_model_overflow(
         self,
@@ -143,9 +357,7 @@ class EngineContextPipeline:
         retries = run.state.retry_state.emergency_compaction_retries
         limit = run.compiled.spec.context_policy.emergency_retry_limit
         if retries >= limit:
-            raise ContextEngineError(
-                f"模型上下文溢出已执行 {retries} 次紧急压缩，达到上限 {limit}"
-            )
+            raise ContextEngineError(f"模型上下文溢出已执行 {retries} 次紧急压缩，达到上限 {limit}")
 
         # Stable Prompt 是高信任、不参与摘要的固定前缀；只压缩其后的动态消息。
         stable_prefix: list[dict[str, Any]] = []
@@ -154,10 +366,9 @@ class EngineContextPipeline:
             stable_prefix = [dict(messages[0])]
             dynamic_messages = messages[1:]
         converted = [_chat_message(message) for message in dynamic_messages]
-        # 保留至少最后两条，并把边界向前移动到 Tool Pair 之前。
-        cutoff = max(0, len(dynamic_messages) - 2)
-        while cutoff > 0 and str(dynamic_messages[cutoff].get("role") or "") == "tool":
-            cutoff -= 1
+        # 三路压缩共用边界：至少保留最后两条，并把边界回退到 Tool Pair 之前。
+        kept = find_compaction_boundary(converted, keep_messages=2, keep_tokens=None)
+        cutoff = len(dynamic_messages) - kept
         if cutoff <= 0:
             raise ContextEngineError("上下文溢出但没有可继续压缩的历史消息")
 
@@ -189,6 +400,10 @@ class EngineContextPipeline:
         plan = self._plan_context(run, recovered_state)
         window, _source = self._resolve_window(run)
         projected = sum(count_tokens(str(m.get("content") or "")) for m in recovered)
+        # G5 §5.2：overflow 恢复后的真实输入与 prepare_context 同款 on_context 拦截。
+        recovered, projected = await self._apply_on_context_hooks(
+            run, plan, recovered, projected, window
+        )
         self._emit_context_built(run, plan, projected, window)
         run.events.append(
             self._event(
@@ -219,7 +434,7 @@ class EngineContextPipeline:
         """
         if self._memory_runtime is None or not run.compiled.spec.memory_policy.enabled:
             return []
-        query = str(run.request.input or "").strip()
+        query = runtime_input_text(run.request.input).strip()
         if not query:
             return []
 
@@ -285,33 +500,89 @@ class EngineContextPipeline:
 
         window, _source = self._resolve_window(run)
         snapshot = run.state.model_copy(update={"messages": messages})
-        effective_input = str(run.request.input or "") if current_input is None else current_input
+        effective_input = (
+            runtime_input_text(run.request.input) if current_input is None else current_input
+        )
         return self._context_engine.plan(
             ContextRequest(
                 spec=run.compiled.spec,
                 state=snapshot,
                 user_input=effective_input,
                 context_window_tokens=window,
-                skill_catalog=tuple(run.skill_catalog),
+                section_items=tuple(
+                    sections_to_context_items(self._collect_sections(run), count_text=count_tokens)
+                ),
             )
         )
 
-    def _emit_planned(self, run: Any, plan: Any, window: int, source: str) -> None:
+    def _collect_sections(self, run: Any) -> list[Any]:
+        """收集全部 ContextSection（G9 §12.3.1）：内置贡献者 + 宿主贡献者。
+
+        贡献者异常 → ``policy.decision(outcome="context_section_failed")`` 可见
+        降级，该贡献者的段缺席（Manifest 如实记录缺席事实），不阻断 Run。
+        """
+        sections: list[Any] = []
+        for index, contributor in enumerate((*BUILTIN_CONTRIBUTORS, *self._context_contributors)):
+            try:
+                produced = contributor.sections(run)
+            except Exception as exc:  # noqa: BLE001 - 可见降级，不静默吞
+                run.events.append(
+                    self._event(
+                        run,
+                        EventType.POLICY_DECISION,
+                        {
+                            "action": "degrade",
+                            "reason": "context_section_failed",
+                            "outcome": "context_section_failed",
+                            "contributor_index": index,
+                            "contributor": type(contributor).__name__,
+                            "error": str(exc)[:256],
+                        },
+                    )
+                )
+                continue
+            if produced:
+                sections.extend(produced)
+        return sections
+
+    def _emit_planned(
+        self,
+        run: Any,
+        plan: Any,
+        window: int,
+        source: str,
+        *,
+        planned_input_tokens: int | None = None,
+        tool_schema_tokens: int = 0,
+    ) -> None:
+        payload = {
+            "budget_tokens": plan.budget.max_input_tokens,
+            "sections": dict(plan.tokens_by_kind),
+            "window_source": source,
+            "context_window_tokens": window,
+            "planned_input_tokens": (
+                plan.planned_input_tokens if planned_input_tokens is None else planned_input_tokens
+            ),
+        }
+        if tool_schema_tokens:
+            payload["tool_schema_tokens"] = tool_schema_tokens
         run.events.append(
             self._event(
                 run,
                 EventType.CONTEXT_PLANNED,
-                {
-                    "budget_tokens": plan.budget.max_input_tokens,
-                    "sections": dict(plan.tokens_by_kind),
-                    "window_source": source,
-                    "context_window_tokens": window,
-                    "planned_input_tokens": plan.planned_input_tokens,
-                },
+                payload,
             )
         )
 
-    def _emit_context_built(self, run: Any, plan: Any, projected: int, window: int) -> None:
+    def _emit_context_built(
+        self,
+        run: Any,
+        plan: Any,
+        projected: int,
+        window: int,
+        *,
+        tool_schema_tokens: int = 0,
+    ) -> None:
         from ksadk.harness.context_manifest import build_manifest
 
         previous = run.context_manifest
@@ -329,28 +600,38 @@ class EngineContextPipeline:
             for section in manifest.sections
             if section.included
         }
-        run.events.append(
-            self._event(
-                run,
-                EventType.CONTEXT_BUILT,
-                {
-                    "manifest_id": manifest.manifest_id,
-                    "stable_prompt_hash": manifest.stable_prompt_hash,
-                    "planned_tokens": manifest.planned_tokens,
-                    "projected_tokens": manifest.projected_tokens,
-                    "context_window_tokens": window,
-                    "sections": sections,
-                    "supersedes": manifest.supersedes or "",
-                },
-            )
-        )
+        payload = {
+            "manifest_id": manifest.manifest_id,
+            "stable_prompt_hash": manifest.stable_prompt_hash,
+            "planned_tokens": manifest.planned_tokens,
+            "projected_tokens": manifest.projected_tokens,
+            "context_window_tokens": window,
+            "sections": sections,
+            "supersedes": manifest.supersedes or "",
+        }
+        if tool_schema_tokens:
+            payload["tool_schema_tokens"] = tool_schema_tokens
+        run.events.append(self._event(run, EventType.CONTEXT_BUILT, payload))
         if self._prompt_cache_tracker is not None:
+            # G13 §16.2 一期：稳定前缀 Hash 覆盖 stable 段（project_docs/
+            # skill_catalog/mcp_catalog）——装配顺序保证它们物理前置，本
+            # Hash 即缓存边界断言的记账面。
+            stable_material = manifest.stable_prompt_hash
+            for item in plan.selected:
+                if getattr(item, "stable", False):
+                    content = item.content if isinstance(item.content, str) else str(item.content)
+                    stable_material += (
+                        f"|{item.item_id}:{hashlib.sha256(content.encode('utf-8')).hexdigest()}"
+                    )
+            stable_prefix_hash = (
+                "sha256:" + hashlib.sha256(stable_material.encode("utf-8")).hexdigest()
+            )
+            scope = (
+                f"{run.state.tenant_id}:{run.state.agent_id}:{run.compiled.spec.model.profile_ref}"
+            )
             diagnostic = self._prompt_cache_tracker.observe(
-                scope=(
-                    f"{run.state.tenant_id}:{run.state.agent_id}:"
-                    f"{run.compiled.spec.model.profile_ref}"
-                ),
-                stable_prompt_hash=manifest.stable_prompt_hash,
+                scope=scope,
+                stable_prompt_hash=stable_prefix_hash,
             )
             run.events.append(
                 self._event(
@@ -362,62 +643,260 @@ class EngineContextPipeline:
                     },
                 )
             )
+            # 边界断言（G13 §16.2）：stable 前缀在 Revision 生命周期内变化
+            # 即发事件（可见，不阻塞）。cold_start 是首个观察，不算断裂。
+            if diagnostic.cache_break and diagnostic.reason not in ("cold_start",):
+                run.events.append(
+                    self._event(
+                        run,
+                        EventType.CONTEXT_CACHE_BOUNDARY_BROKEN,
+                        {
+                            "scope": scope,
+                            "stable_prefix_hash": stable_prefix_hash,
+                            "previous_hash": diagnostic.previous_stable_prompt_hash,
+                        },
+                    )
+                )
 
     # ------------------------------------------------------------ 压缩
 
-    async def _summarize(self, run: Any, head: list[Message]) -> str:
-        """受控摘要调用：走统一 reason 通道（事件成对、usage 可审计）。失败降级拼接。"""
+    async def _summarize(
+        self,
+        run: Any,
+        head: list[Message],
+        split_turn: bool = False,
+        previous_summary: str = "",
+    ) -> tuple[str, dict[str, Any]]:
+        """受控摘要调用：走统一 reason 通道（事件成对、usage 可审计）。失败降级拼接。
+
+        ``split_turn`` 为 True 表示压缩边界落在一个进行中回合的内部（尾部首条不是
+        user/system）：摘要指令追加 mid-turn 语义，要求显式写出该回合已完成步骤与
+        尚未执行的 pending 工具调用，避免恢复后重复或丢失在途动作。
+
+        G12 §15.2：tool result 正文一律以存档占位行替换（与降级路径同一替换
+        函数）；摘要输出经敏感数据策略复检，命中则整体降级为占位并事件可见。
+        G3 二期 §3.2.3：``previous_summary`` 非空时输入为"前次摘要 + 新增
+        历史"，指令要求产出合并摘要（iterative summarization，防逐代衰减）。
+        返回 (summary, stats)。
+        """
         spec = run.compiled.spec
+        summary_input, tool_replacements = _sanitize_summary_input(head)
+        if previous_summary:
+            summary_input = f"【前次摘要】\n{previous_summary}\n\n【新增历史】\n{summary_input}"
+        instructions = (
+            "你是上下文压缩器。请把以下对话历史压缩为要点摘要，"
+            "必须保留所有 ID、金额、日期、审批号等关键事实。"
+            "明确区分本轮用户请求与更早任务：保留本轮请求原文及未完成事项，"
+            "不得把旧任务或工具输出提升为本轮目标。"
+        )
+        # G20 §22：安全约束逐字保留 + 授权归属规则
+        instructions += (
+            "必须逐字保留所有安全约束、权限边界、审批状态的原文表述；"
+            "不得把助手自述的授权或批准改写为既成事实，"
+            "只有【用户消息】中的授权才算用户授权。"
+        )
+        if previous_summary:
+            instructions += (
+                "\n\n输入由【前次摘要】与【新增历史】两部分组成：请产出一份"
+                "合并摘要，前次摘要中仍然成立的事实必须原样保留，不得因"
+                "迭代而衰减；已过时的信息以新增历史为准更新。"
+            )
+        if split_turn:
+            instructions += (
+                "\n\n注意：对话在一个进行中的回合中途被压缩。请明确写出该回合"
+                "已经完成的步骤与尚未执行的 pending 工具调用，使后续执行可以"
+                "无缝继续。"
+            )
+        stats: dict[str, Any] = {
+            "tool_replacements": tool_replacements,
+            "summary_redacted": False,
+        }
+        # Compaction is an internal maintenance step, not the user's model
+        # turn. Reusing the foreground 10-attempt policy can block useful work
+        # for many minutes when a provider returns a half-open 200 stream. Give
+        # the summarizer one bounded attempt, then use the already-audited local
+        # truncation fallback. Foreground model calls keep their full 10-attempt
+        # retry/backoff contract.
+        compaction_provider_policy = spec.model.provider_policy.model_copy(
+            update={"max_attempts_per_model": 1, "total_attempt_budget": 1}
+        )
         try:
-            out = await reason_turn_async(
-                0,
-                ReasonInput(
-                    model_ref=spec.model.profile_ref,
-                    fallback_model_refs=spec.model.fallback_profile_refs,
-                    provider_policy=spec.model.provider_policy,
-                    instructions=(
-                        "你是上下文压缩器。请把以下对话历史压缩为要点摘要，"
-                        "必须保留所有 ID、金额、日期、审批号等关键事实。"
+            async with asyncio.timeout(30):
+                out = await reason_turn_async(
+                    0,
+                    ReasonInput(
+                        model_ref=spec.model.profile_ref,
+                        fallback_model_refs=(),
+                        provider_policy=compaction_provider_policy,
+                        instructions=instructions,
+                        messages=[{"role": "user", "content": summary_input}],
+                        tools=[],
+                        reasoner=self._reasoner,
+                        agent_id=run.state.agent_id,
+                        user_id=run.state.user_id,
+                        session_id=run.state.session_id,
+                        run_id=run.handle.run_id,
+                        seq_start=run.seq,
+                        max_turns=1,
+                        reasoning_effort=(
+                            str((getattr(run.request, "config", {}) or {}).get("effort") or "")
+                            .strip()
+                            .lower()
+                            or None
+                        ),
                     ),
-                    messages=[{"role": "user", "content": "\n".join(m.content for m in head)}],
-                    tools=[],
-                    reasoner=self._reasoner,
-                    agent_id=run.state.agent_id,
-                    user_id=run.state.user_id,
-                    session_id=run.state.session_id,
-                    run_id=run.handle.run_id,
-                    seq_start=run.seq,
-                    max_turns=1,
-                ),
-            )
-        except Exception as exc:  # noqa: BLE001 - 摘要失败降级为截断拼接，不阻断 Run
+                )
+        except Exception as exc:  # noqa: BLE001 - 摘要失败降级/熔断/413 逃生
             if isinstance(exc, ModelFailoverExhausted):
                 for event in exc.events:
                     run.events.append(event)
                     run.seq = max(run.seq, event.seq_id)
-            text = "\n".join(m.content for m in head)
+            # G18 ③ 413 逃生：payload_too_large / context_length / HTTP 413
+            # → 减半摘要输入再试一次，仍失败则进熔断计数。
+            err_str = str(exc)
+            is_413 = (
+                "413" in err_str or "payload_too_large" in err_str or "context_length" in err_str
+            )
+            if is_413:
+                half = summary_input[: max(1, len(summary_input) // 2)]
+                try:
+                    async with asyncio.timeout(30):
+                        out = await reason_turn_async(
+                            0,
+                            ReasonInput(
+                                model_ref=spec.model.profile_ref,
+                                fallback_model_refs=(),
+                                provider_policy=compaction_provider_policy,
+                                instructions=instructions,
+                                messages=[{"role": "user", "content": half}],
+                                tools=[],
+                                reasoner=self._reasoner,
+                                agent_id=run.state.agent_id,
+                                user_id=run.state.user_id,
+                                session_id=run.state.session_id,
+                                run_id=run.handle.run_id,
+                                seq_start=run.seq,
+                                max_turns=1,
+                                reasoning_effort=(
+                                    str(
+                                        (getattr(run.request, "config", {}) or {}).get("effort")
+                                        or ""
+                                    )
+                                    .strip()
+                                    .lower()
+                                    or None
+                                ),
+                            ),
+                        )
+                    # 413 逃生成功：走正常成功路径
+                    for ev in out.events:
+                        # The summarizer shares the foreground reason loop for
+                        # provider policy and usage accounting, but its output
+                        # is internal context state rather than an assistant
+                        # reply. Mark every emitted event so adapters can keep
+                        # summary text out of the conversation while retaining
+                        # an auditable model-call trace.
+                        ev.payload.setdefault("purpose", "compaction")
+                        run.events.append(ev)
+                        run.seq = max(run.seq, ev.seq_id)
+                    summary = (
+                        str(out.new_messages[0].get("content") or "") if out.new_messages else ""
+                    )
+                    run.events.append(
+                        self._event(
+                            run,
+                            EventType.CONTEXT_RECOVERED,
+                            {"reason": "compaction_summary_413_fallback"},
+                        )
+                    )
+                    # 413 逃生成功重置失败计数
+                    _rs = getattr(run.state, "retry_state", None)
+                    if _rs is not None and hasattr(_rs, "model_copy"):
+                        run.state.retry_state = _rs.model_copy(
+                            update={"consecutive_compaction_failures": 0}
+                        )
+                    return summary, stats
+                except Exception:  # noqa: BLE001 - 413 回退仍失败，进降级/熔断
+                    pass
+            # G18 ① 连续失败熔断：连续 3 次 → 抛 ContextEngineError，停止空转
+            _rs = getattr(run.state, "retry_state", None)
+            if _rs is not None and hasattr(_rs, "model_copy"):
+                failures = _rs.consecutive_compaction_failures + 1
+                run.state.retry_state = _rs.model_copy(
+                    update={"consecutive_compaction_failures": failures}
+                )
+            else:
+                failures = 0
+            if failures >= 3:
+                run.events.append(
+                    self._event(
+                        run,
+                        EventType.CONTEXT_RECOVERED,
+                        {
+                            "reason": "compaction_circuit_breaker_open",
+                            "error": f"3 consecutive summary failures; last: {err_str[:128]}",
+                        },
+                    )
+                )
+                from ksadk.harness.context_engine import ContextEngineError
+
+                raise ContextEngineError(
+                    "compaction circuit breaker open (3 consecutive summary failures)"
+                )
+            text = summary_input
             # 降级不静默（§6.4 "不静默丢弃"）：真实模型评测曾把摘要失败
             # 吞成 0-token Run；发 context.recovered 让降级可观测可告警。
+            # G12：降级拼接同样只使用脱敏输入（tool result 不回填）。
+            reason = (
+                "compaction_summary_413_fallback_failed"
+                if is_413
+                else "compaction_summary_failed:degraded_truncation"
+            )
             run.events.append(
                 self._event(
                     run,
                     EventType.CONTEXT_RECOVERED,
                     {
-                        "reason": "compaction_summary_failed:degraded_truncation",
+                        "reason": reason,
                         "error": str(exc)[:256],
                     },
                 )
             )
-            return text[:2000] + ("\n…[截断]" if len(text) > 2000 else "")
+            return text[:2000] + ("\n…[截断]" if len(text) > 2000 else ""), stats
         for ev in out.events:
-            # 压缩摘要是管线内部模型调用，不对应任何 ContextManifest；
-            # usage 事件标记 purpose=compaction（真实模型评测暴露：否则
-            # Actual↔Manifest 配对率虚低，且压缩花费不可归因）。
-            if ev.event_type == EventType.USAGE_REPORTED:
-                ev.payload.setdefault("purpose", "compaction")
+            # 压缩摘要是管线内部模型调用，不对应任何 ContextManifest，也不是
+            # 面向用户的 assistant message。全部事件显式标记 purpose，既让
+            # usage 可归因，也让 adapter 能隔离摘要正文而保留审计生命周期。
+            ev.payload.setdefault("purpose", "compaction")
             run.events.append(ev)
             run.seq = max(run.seq, ev.seq_id)
-        return str(out.new_messages[0].get("content") or "") if out.new_messages else ""
+        summary = str(out.new_messages[0].get("content") or "") if out.new_messages else ""
+        # G12：摘要输出敏感复检——摘要模型可能是另一供应商，命中即整体
+        # 降级为占位（可见降级，不外泄敏感明文）。
+        if self._sensitive_policy is not None and summary:
+            hit = None
+            try:
+                hit = self._sensitive_policy.sensitive_match(summary)
+            except Exception:  # noqa: BLE001 - 策略故障不阻断压缩
+                hit = None
+            if hit:
+                stats["summary_redacted"] = True
+                run.events.append(
+                    self._event(
+                        run,
+                        EventType.CONTEXT_RECOVERED,
+                        {
+                            "reason": "compaction_summary_sensitive_redacted",
+                            "policy": "sensitive_patterns",
+                        },
+                    )
+                )
+                summary = _REDACTED_SUMMARY_PLACEHOLDER
+        # G18 ① 摘要成功重置连续失败计数
+        _rs = getattr(run.state, "retry_state", None)
+        if _rs is not None and hasattr(_rs, "model_copy"):
+            run.state.retry_state = _rs.model_copy(update={"consecutive_compaction_failures": 0})
+        return summary, stats
 
     async def _compact_history(
         self,
@@ -427,31 +906,63 @@ class EngineContextPipeline:
         trigger: str,
         keep_recent: int,
         budget_tokens: int,
+        keep_recent_tokens: int | None = None,
+        trigger_reason: str | None = None,
     ) -> list[Message] | None:
-        """主动/紧急压缩：摘要 head + 保留 tail + 关键事实重注入，返回新历史。"""
+        """主动/紧急压缩：摘要 head + 保留 tail + 关键事实重注入，返回新历史。
+
+        keep 边界统一由 ``find_compaction_boundary`` 计算：条数上限 ``keep_recent``
+        与 token 预算 ``keep_recent_tokens`` 取更严格者（floor 1），并回退到 Tool
+        Pair 之前。边界落在一个进行中回合内部时置 ``split_turn``，摘要 prompt 与
+        压缩留痕（CompactionRecord / context.compaction.completed）一并带上该语义。
+        """
         from ksadk.harness.context_engine import CompactionRequest
 
         if len(messages) <= keep_recent:
             return None
+        kept = find_compaction_boundary(
+            messages, keep_messages=keep_recent, keep_tokens=keep_recent_tokens
+        )
+        if kept >= len(messages):
+            return None
+        head = messages[: len(messages) - kept]
+        tail = messages[len(messages) - kept :]
+        split_turn = _is_split_turn(head, tail)
+        started_payload: dict[str, Any] = {"phase": "before", "trigger": trigger}
+        if trigger_reason is not None:
+            started_payload["trigger_reason"] = trigger_reason
         run.events.append(
             self._event(
                 run,
                 EventType.CONTEXT_COMPACTION_STARTED,
-                {"phase": "before", "trigger": trigger},
+                started_payload,
             )
         )
         # 长任务方案 §6.4 主动压缩步骤 2：压缩前受控 Memory Flush——
         # 被压缩历史先经提取管线落长期 Memory（审计事件并入事件流）。
-        memory_candidate_refs = self._flush_memory_before_compaction(run, messages[:-keep_recent])
+        memory_candidate_refs = self._flush_memory_before_compaction(run, head)
         before_tokens = sum(count_tokens(m.content) for m in messages)
-        summary = await self._summarize(run, messages[:-keep_recent])
+        # G3 二期 §3.2.3 摘要链：run 内多次压缩逐代链接——上一次记录的摘要
+        # 作为本次合并输入，previous_compaction_id 形成链。
+        previous_record = run.compaction_records[-1] if run.compaction_records else None
+        previous_summary = previous_record.summary if previous_record is not None else ""
+        summary, summary_stats = await self._summarize(
+            run, head, split_turn=split_turn, previous_summary=previous_summary
+        )
+        # G12 §15.2：critical-facts 抽取器吃"敏感正则脱敏后"的原始消息——
+        # 工具结果里的 ID/金额参与抽取（与摘要模型输入分离），命中敏感
+        # 正则的内容替换为占位，不进任何模型输入。
+        masked_messages, sensitive_hits = self._mask_sensitive_messages(messages)
         checkpoint = self._context_engine.compact(
             CompactionRequest(
-                messages=messages,
-                keep_recent=keep_recent,
+                messages=masked_messages,
+                # 用实际保留条数（tail 长度）而非原始 keep_recent，使 compact 内部
+                # 的 head/tail 切分与这里的边界（可能被 token 预算收窄）严格一致，
+                # 关键事实后校验不会对着错误的 head 计算。
+                keep_recent=len(tail),
                 trigger=trigger,
                 summary=summary,
-                compacted_count=len(messages) - keep_recent,
+                compacted_count=len(head),
             )
         )
         compacted_text = (checkpoint.summary or "").strip()
@@ -460,13 +971,11 @@ class EngineContextPipeline:
         new_messages: list[Message] = [
             Message(role=MessageRole.SYSTEM, content=f"【历史摘要】\n{compacted_text}")
         ]
-        new_messages.extend(messages[-keep_recent:])
+        new_messages.extend(tail)
         after_tokens = sum(count_tokens(m.content) for m in new_messages)
         # 长任务方案 §6.4：CompactionRecord（投影变化记录，非新事实源）。
         # 摘要缺失但经重注入保留的事实不算最终丢弃（§8.4.1 "不静默丢弃"）。
-        reinjected = (
-            tuple(checkpoint.dropped_critical_facts) if checkpoint.reinjection else ()
-        )
+        reinjected = tuple(checkpoint.dropped_critical_facts) if checkpoint.reinjection else ()
         record = build_compaction_record(
             run_id=run.handle.run_id,
             trigger=trigger,
@@ -479,7 +988,28 @@ class EngineContextPipeline:
             reinjected_critical_facts=reinjected,
             summary_model_ref=run.compiled.spec.model.profile_ref,
             memory_candidate_refs=tuple(memory_candidate_refs),
+            split_turn=split_turn,
+            sanitized_input=bool(summary_stats.get("tool_replacements") or sensitive_hits),
+            sanitized_replacements=int(summary_stats.get("tool_replacements") or 0)
+            + sensitive_hits,
+            previous_compaction_id=previous_record.compaction_id
+            if previous_record is not None
+            else "",
         )
+        # G3 二期质量闸门（§9.2 评审决策：硬编码 + 事件可见，不阻塞）：
+        # 每 3 代压缩执行一次关键事实覆盖率比对——当代（retained ∪ reinjected）
+        # 事实数低于上一代即标 quality_degraded。真实降级案例出现后再配置化。
+        generation = len(run.compaction_records) + 1
+        quality_degraded = False
+        if previous_record is not None and generation % 3 == 0:
+            current_facts = len(
+                set(record.retained_critical_facts) | set(record.reinjected_critical_facts)
+            )
+            previous_facts = len(
+                set(previous_record.retained_critical_facts)
+                | set(previous_record.reinjected_critical_facts)
+            )
+            quality_degraded = current_facts < previous_facts
         run.compaction_records.append(record)
         run.events.append(
             self._event(
@@ -496,6 +1026,13 @@ class EngineContextPipeline:
                     "compaction_id": record.compaction_id,
                     "before_tokens": record.before_tokens,
                     "after_tokens": record.after_tokens,
+                    "split_turn": split_turn,
+                    "sanitized_input": record.sanitized_input,
+                    "sanitized_replacements": record.sanitized_replacements,
+                    "summary_redacted": bool(summary_stats.get("summary_redacted")),
+                    "previous_compaction_id": record.previous_compaction_id,
+                    "generation": generation,
+                    "quality_degraded": quality_degraded,
                     "quality_checks": record.quality_checks(),
                     "memory_candidate_refs": list(record.memory_candidate_refs),
                 },
@@ -503,6 +1040,108 @@ class EngineContextPipeline:
         )
         return new_messages
 
+    def _mask_sensitive_messages(self, messages: list[Message]) -> tuple[list[Message], int]:
+        """G12：对 tool 消息内容做敏感正则替换（占位），返回 (掩码副本, 命中数)。
+
+        仅 tool 消息参与掩码——摘要模型已经吃不到 tool 正文（§15.2 第一
+        管线），本函数服务 critical-facts 抽取通道；user/assistant 消息的
+        关键事实是压缩合同要保住的对象，不掩码。
+        """
+        policy = self._sensitive_policy
+        if policy is None or not getattr(policy, "enabled", True):
+            return messages, 0
+        patterns = tuple(getattr(policy, "sensitive_patterns", ()) or ())
+        if not patterns:
+            return messages, 0
+        masked: list[Message] = []
+        hits = 0
+        for message in messages:
+            if message.role is not MessageRole.TOOL:
+                masked.append(message)
+                continue
+            content = message.content
+            replaced = 0
+            for pattern in patterns:
+                content, count = re.subn(pattern, "[已脱敏]", content)
+                replaced += count
+            if replaced:
+                hits += replaced
+                masked.append(message.model_copy(update={"content": content}))
+            else:
+                masked.append(message)
+        return masked, hits
+
+    async def summarize_branch(self, run: Any, messages: list[Message]) -> CompactionRecord:
+        """分支切换摘要（G2 二期 §2.2.2）：复用 G3 摘要管线生成 BranchSummary。
+
+        切分支时目标分支上下文过长 → 宿主调用本方法：输入走与压缩一致的
+        脱敏规则，产出 CompactionRecord（trigger="branch_switch"）并落
+        context.compaction.started/completed 事件。审计与普通压缩同构，
+        宿主可据 summary 重建目标分支上下文。
+        """
+        run.events.append(
+            self._event(
+                run,
+                EventType.CONTEXT_COMPACTION_STARTED,
+                {"phase": "before", "trigger": "branch_switch"},
+            )
+        )
+        before_tokens = sum(count_tokens(m.content) for m in messages)
+        summary, summary_stats = await self._summarize(run, messages)
+        masked_messages, sensitive_hits = self._mask_sensitive_messages(messages)
+        # 分支摘要不做 head/tail 切分：整个目标分支作为被摘要对象；关键
+        # 事实经 compact 后校验，缺失的经重注入并入 BranchSummary（"不静默
+        # 丢弃"——record.critical_facts_preserved 语义与普通压缩一致）。
+        from ksadk.harness.context_engine import CompactionRequest
+
+        checkpoint = self._context_engine.compact(
+            CompactionRequest(
+                messages=masked_messages,
+                keep_recent=0,
+                trigger="branch_switch",
+                summary=summary,
+                compacted_count=len(messages),
+            )
+        )
+        if checkpoint.reinjection:
+            summary = (summary + "\n\n" + checkpoint.reinjection).strip()
+        record = build_compaction_record(
+            run_id=run.handle.run_id,
+            trigger="branch_switch",
+            before_tokens=before_tokens,
+            after_tokens=sum(count_tokens(m.content) for m in masked_messages),
+            compacted_event_range=(0, len(messages)),
+            summary=summary,
+            retained_critical_facts=tuple(checkpoint.retained_critical_facts),
+            dropped_critical_facts=tuple(checkpoint.dropped_critical_facts),
+            reinjected_critical_facts=tuple(checkpoint.dropped_critical_facts),
+            summary_model_ref=run.compiled.spec.model.profile_ref,
+            split_turn=False,
+            sanitized_input=bool(summary_stats.get("tool_replacements") or sensitive_hits),
+            sanitized_replacements=int(summary_stats.get("tool_replacements") or 0)
+            + sensitive_hits,
+        )
+        run.compaction_records.append(record)
+        run.events.append(
+            self._event(
+                run,
+                EventType.CONTEXT_COMPACTION_COMPLETED,
+                {
+                    "phase": "after",
+                    "trigger": "branch_switch",
+                    "compacted_until_seq_id": len(messages),
+                    "compaction_id": record.compaction_id,
+                    "before_tokens": record.before_tokens,
+                    "after_tokens": record.after_tokens,
+                    "split_turn": False,
+                    "sanitized_input": record.sanitized_input,
+                    "sanitized_replacements": record.sanitized_replacements,
+                    "quality_checks": record.quality_checks(),
+                },
+            )
+        )
+        return record
+
     def _flush_memory_before_compaction(self, run: Any, head: list[Message]) -> list[str]:
         """压缩前受控 Memory Flush（§6.4 步骤 2）。
 
@@ -541,12 +1180,145 @@ class EngineContextPipeline:
         return [ref for ref in committed if ref]
 
 
+def find_compaction_boundary(
+    messages: list[Message], *, keep_messages: int, keep_tokens: int | None = None
+) -> int:
+    """三路压缩（proactive/emergency/overflow）共用的 keep 边界（G3 一期）。
+
+    从尾部反向累计 count_tokens，达到 keep_tokens 停止；keep_messages 是条数
+    上限，两者取更严格者（floor 1：至少保留最后一条消息）。之后把边界回退到
+    tool-pair 之前——首条保留消息是 tool 时其 assistant 调用会落在被摘要段，
+    pair 完整性优先于 token 预算。返回保留尾部条数；返回 len(messages) 表示
+    无可压缩空间。
+
+    注意：pair 回退也会把 keep 推到 total，因此返回值 ``== len(messages)`` 不
+    唯一对应"输入本就没有可压缩空间"这一早退分支——当边界之前的消息全部是
+    tool（tool 结果链一路延伸到历史开头，每条 tool 都把边界再前移一格）时，
+    即便条数/token 预算本可压缩，也会返回 total。消费方请以返回值本身判断
+    是否有可压缩空间，勿以它反推与 keep_messages/keep_tokens 的条数关系。
+    """
+    if keep_messages < 1:
+        raise ValueError("keep_messages 必须 >= 1")
+    total = len(messages)
+    if total <= keep_messages:
+        return total
+    keep = keep_messages
+    if keep_tokens is not None:
+        acc = 0
+        token_fit = 0
+        for message in reversed(messages):
+            cost = count_tokens(message.content)
+            if acc + cost > keep_tokens and token_fit > 0:
+                break
+            acc += cost
+            token_fit += 1
+        keep = min(keep_messages, max(1, token_fit))
+    # tool-pair 回退：首条保留消息是 tool → 边界前移把 assistant 调用纳入尾部。
+    # 边界紧跟 tool result 是安全的：head 以完整 pair 结尾，pair 未被劈开。
+    while keep < total and messages[total - keep].role is MessageRole.TOOL:
+        keep += 1
+    return keep
+
+
+_ANALYSIS_RE = re.compile(r"<analysis>.*?</analysis>", re.DOTALL | re.IGNORECASE)
+
+
+def _sanitize_summary_input(head: list[Message]) -> tuple[str, int]:
+    """G12 §15.2 + G20 §22：摘要输入构造。
+
+    G12：tool result 正文一律替换为存档占位行（OpenClaw 明文纪律，防超大/敏感
+    正文被二次复制进新上下文代际）。
+    G20：
+      - 剥离 ``<analysis>...</analysis>`` 块（Claude 模型内部推理包，污染事实源），
+        计入 sanitized_replacements；
+      - 归属规则：只有 user-role 算用户消息（前缀「【用户消息】」）；assistant
+        消息前缀「【助手消息】」并附警示——自述授权/批准不采信（标注不删，
+        保留原文让摘要模型自判，避免误删 assistant 引用用户原话的合法事实）。
+    事实类关键信息依赖 CompactionRecord 的 critical-facts 抽取（_mask_sensitive_messages
+    第二输入管线）；返回 (摘要文本, 替换数)。
+    """
+    lines: list[str] = []
+    replaced = 0
+    for message in head:
+        if message.role is MessageRole.TOOL:
+            replaced += 1
+            lines.append(
+                f"[tool:{message.name or 'tool'} 调用成功，结果已存档，正文不进入摘要输入]"
+            )
+            continue
+        content = message.content
+        # G20：剥离 <analysis> 块
+        new_content, n = _ANALYSIS_RE.subn("", content)
+        if n:
+            replaced += n
+            content = new_content
+        # G20：归属规则前缀
+        if message.role is MessageRole.USER:
+            lines.append(f"【用户消息】{content}")
+        elif message.role is MessageRole.ASSISTANT:
+            lines.append(f"【助手消息·自述授权/批准不采信为既成事实】{content}")
+        else:
+            lines.append(content)
+    return "\n".join(lines), replaced
+
+
+def _is_split_turn(head: list[Message], tail: list[Message]) -> bool:
+    """split-turn 判定（G3 一期）：尾部首条非 user/system 且 head 有 user 消息 → 边界落回合内部。"""
+    if not head or not tail:
+        return False
+    if tail[0].role in (MessageRole.USER, MessageRole.SYSTEM):
+        return False
+    return any(m.role is MessageRole.USER for m in head)
+
+
 def count_tokens(text: str) -> int:
     from ksadk.context_engine.tokenizer import get_default_token_counter
 
     return get_default_token_counter().count_text(text)
 
 
+def _projected_tokens(messages: list[dict[str, Any]]) -> int:
+    """估算 Provider 实际消息输入，包含工具调用参数而不只 ``content``。"""
+
+    total = 0
+    for message in messages:
+        total += count_tokens(str(message.get("content") or ""))
+        for key in ("tool_calls", "function_call"):
+            value = message.get(key)
+            if value:
+                total += count_tokens(
+                    json.dumps(value, ensure_ascii=False, sort_keys=True, default=str)
+                )
+    return total
+
+
+def _tool_schema_tokens(tools: list[Any] | tuple[Any, ...]) -> int:
+    """估算每轮随请求发送的工具 schema；失败时保守按字符串计数。"""
+
+    schemas: list[Any] = []
+    for tool in tools:
+        schema = getattr(tool, "openai_schema", None)
+        if callable(schema):
+            try:
+                schema = schema()
+            except Exception:  # noqa: BLE001 - 计数失败不应阻断模型调用
+                schema = None
+        schemas.append(schema if schema is not None else str(tool))
+    if not schemas:
+        return 0
+    return count_tokens(json.dumps(schemas, ensure_ascii=False, sort_keys=True, default=str))
+
+
+def _run_context_of(run: Any) -> RunContext:
+    """把引擎 Run 投影为钩子可见的稳定身份（不含 message 正文）。"""
+    return RunContext(
+        run_id=str(run.handle.run_id),
+        agent_id=str(run.state.agent_id),
+        user_id=str(run.state.user_id or ""),
+        session_id=str(run.state.session_id or ""),
+    )
+
+
 def _chat_message(message: dict[str, Any]) -> Message:
     """把 OpenAI 消息投影为压缩/规划使用的稳定 Message 形态。"""
     role_value = str(message.get("role") or "user")
@@ -576,4 +1348,4 @@ def _keyword_score(query: str, content: str) -> float:
     return round(hits / len(terms), 4)
 
 
-__all__ = ["EngineContextPipeline", "count_tokens"]
+__all__ = ["EngineContextPipeline", "count_tokens", "find_compaction_boundary"]