agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/conversations/runtime_compaction.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import asyncio
+import logging
 import uuid
 from typing import Any, Callable, Dict, Mapping, Optional, Sequence
 
@@ -13,6 +15,8 @@ from ksadk.conversations.context import (
 )
 from ksadk.conversations.model_context import (
     estimate_text_tokens,
+    get_auto_compact_hard_limit_tokens,
+    get_auto_compact_soft_limit_tokens,
     get_auto_compact_threshold_percentage,
     get_auto_compact_threshold_tokens,
 )
@@ -33,11 +37,14 @@ from ksadk.conversations.runtime_payloads import CompactionPlan
 from ksadk.conversations.runtime_persistence import append_context_checkpoint_event
 from ksadk.conversations.semantic_summary import (
     extract_pinned_state,
+    extract_working_state,
     find_pinned_group_indexes,
     summarize_compaction,
 )
 from ksadk.sessions import SessionEvent, resolve_session_service
 
+logger = logging.getLogger(__name__)
+
 
 def _plan_compaction(
     events: Sequence[SessionEvent],
@@ -47,8 +54,19 @@ def _plan_compaction(
     pending_events: Sequence[SessionEvent] | None = None,
     force: bool = False,
     keep_tail_groups: int | None = None,
+    prompt_integration_mode: str = "",
+    compaction_owner: str = "",
 ) -> CompactionPlan:
-    """根据当前 transcript 计算是否需要做 checkpoint compaction。"""
+    """根据当前 transcript 计算是否需要做 checkpoint compaction。
+
+    ``compaction_owner=="ksadk"`` 时走双阈值（soft 50% / hard ~84%），命中且
+    ``len(groups) > tail_groups`` 时触发 proactive compact（soft=整理，hard=强制止血）。
+    未显式提供 owner 的旧调用继续以 ``ksadk_hosted`` 作为兼容判据。
+    ``force=True``（PTL）始终绕过阈值，``trigger_band="emergency"``。
+
+    compaction_owner 硬门控（方案 §6.2）：native/framework owner 不运行 KsADK 第二套
+    压缩；framework-assisted Runner 可显式声明 owner=ksadk 使用平台压缩。
+    """
 
     compacted_until = compacted_until_seq_id(list(events))
     transcript_events = [
@@ -82,9 +100,46 @@ def _plan_compaction(
     total_estimated_tokens = sum(
         estimate_text_tokens(extract_event_text(event)) for event in combined_events
     )
-    if not force and (
-        len(groups) <= tail_groups or total_estimated_tokens <= auto_compact_threshold_tokens
-    ):
+    # 是否启用双阈值由 compaction ownership 决定，而不是由 Prompt 接管模式决定。
+    # framework-assisted LangGraph 也可以把压缩明确交给 KsADK；native/framework
+    # owner 则继续使用各自原生机制，避免双重压缩。
+    is_ksadk_hosted = compaction_owner == "ksadk" or (
+        not compaction_owner and prompt_integration_mode == "ksadk_hosted"
+    )
+    soft_limit_tokens = (
+        get_auto_compact_soft_limit_tokens(resolved_model_metadata) if is_ksadk_hosted else None
+    )
+    hard_limit_tokens = (
+        get_auto_compact_hard_limit_tokens(resolved_model_metadata) if is_ksadk_hosted else None
+    )
+
+    # 触发带判定。force（PTL）优先 → emergency，绕过阈值。
+    groups_enough = len(groups) > tail_groups
+    if force:
+        trigger_band = "emergency"
+        should_by_threshold = True
+    elif is_ksadk_hosted and soft_limit_tokens is not None and hard_limit_tokens is not None:
+        # 双阈值：hard 优先于 soft。二者都需 groups 充足，否则 none（避免每轮压缩）。
+        if not groups_enough:
+            trigger_band = "none"
+            should_by_threshold = False
+        elif total_estimated_tokens > hard_limit_tokens:
+            trigger_band = "hard"
+            should_by_threshold = True
+        elif total_estimated_tokens > soft_limit_tokens:
+            trigger_band = "soft"
+            should_by_threshold = True
+        else:
+            trigger_band = "none"
+            should_by_threshold = False
+    else:
+        # 非 ksadk_hosted → 旧单阈值。trigger_band="" 表示门控未启用（旧路径）。
+        trigger_band = ""
+        should_by_threshold = total_estimated_tokens > auto_compact_threshold_tokens
+
+    # early-return：groups 不足或（非 force 且未超阈值）。保留 len(groups)<=tail_groups 早退，
+    # 避免每轮压缩。force 仍绕过此早退的阈值部分，但 groups 不足时 force 也无可压缩（下方）。
+    if not force and (len(groups) <= tail_groups or not should_by_threshold):
         return CompactionPlan(
             should_compact=False,
             groups_to_compact=[],
@@ -96,6 +151,9 @@ def _plan_compaction(
             auto_compact_threshold_percentage=auto_compact_threshold_percentage,
             pinned_group_indexes=pinned_group_indexes,
             pinned_state=pinned_state,
+            soft_limit_tokens=soft_limit_tokens,
+            hard_limit_tokens=hard_limit_tokens,
+            trigger_band=trigger_band,
         )
 
     compactable_indexes = [
@@ -121,6 +179,9 @@ def _plan_compaction(
             auto_compact_threshold_percentage=auto_compact_threshold_percentage,
             pinned_group_indexes=pinned_group_indexes,
             pinned_state=pinned_state,
+            soft_limit_tokens=soft_limit_tokens,
+            hard_limit_tokens=hard_limit_tokens,
+            trigger_band=trigger_band,
         )
 
     compacted_until_seq_id_value = groups_to_compact[-1][-1].seq_id or None
@@ -136,6 +197,9 @@ def _plan_compaction(
         compacted_until_seq_id=compacted_until_seq_id_value,
         pinned_group_indexes=pinned_group_indexes,
         pinned_state=pinned_state,
+        soft_limit_tokens=soft_limit_tokens,
+        hard_limit_tokens=hard_limit_tokens,
+        trigger_band=trigger_band,
     )
 
 
@@ -148,6 +212,7 @@ async def preview_auto_compaction(
     model: Optional[str] = None,
     model_metadata: Mapping[str, Any] | None = None,
     session_service_provider: Callable[[], Any] | None = None,
+    prompt_integration_mode: str = "",
 ) -> CompactionPlan:
     """在真正写入 turn 之前预估是否会触发自动压缩。
 
@@ -214,9 +279,81 @@ async def preview_auto_compaction(
         model=model,
         model_metadata=resolved_model_metadata,
         pending_events=[pending_event],
+        prompt_integration_mode=prompt_integration_mode,
+    )
+
+
+def _working_state_from_checkpoint(checkpoint: Any) -> Any:
+    """§8.1：从上一个 context_checkpoint 事件解析 WorkingState（用于缺失字段合并）。
+
+    checkpoint metadata 由 compact_conversation_history 写入（仅 ksadk_hosted）。无 checkpoint
+    或无 working_state 键时返回 None。重建的 WorkingState 仅用于回填 current_goal/constraints
+    等关键字段，不恢复 pending_tools/approvals（那些以事实事件为准）。
+    """
+    if checkpoint is None:
+        return None
+    meta = getattr(checkpoint, "metadata", None) or {}
+    ws_audit = meta.get("working_state")
+    if not isinstance(ws_audit, dict):
+        return None
+    from ksadk.conversations.semantic_summary import WorkingState
+
+    return WorkingState(
+        current_goal=str(ws_audit.get("current_goal") or ""),
+        next_action=ws_audit.get("next_action"),
+        completed_steps=list(ws_audit.get("completed_steps") or []),
+        constraints=list(ws_audit.get("constraints") or []),
+        source_seq_range=tuple(ws_audit.get("source_seq_range") or (0, 0)),  # type: ignore[arg-type]
     )
 
 
+async def _maybe_memory_flush(
+    events: Sequence[SessionEvent],
+    *,
+    user_id: str = "",
+    agent_id: str = "",
+) -> dict[str, Any] | None:
+    """压缩前 best-effort Memory Flush（方案 §9.2）。
+
+    门控：``KSADK_MEMORY_FLUSH_ENABLED``（默认关，避免在无 Memory Provider 时改变行为）+
+    ``KSADK_MEMORY_FLUSH_BEFORE_COMPACTION``（默认开，但需前者总开关）。提取候选交
+    ``MemoryCoordinator.flush_candidates``，Policy 决定 commit/reject。失败返回 ``failed``，不抛。
+    """
+    import os as _os
+
+    if _os.environ.get("KSADK_MEMORY_FLUSH_ENABLED", "").strip().lower() not in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    ):
+        return None
+    try:
+        from ksadk.context_engine.policies import ContextPolicy
+        from ksadk.memory.coordinator import MemoryCoordinator
+        from ksadk.memory.extraction import propose_memory_candidates
+        from ksadk.memory.providers.local_sqlite import resolve_default_memory_provider
+
+        policy = ContextPolicy.from_env()
+        if not policy.compaction.flush_memory_before_compaction:
+            return None
+        # 持久化 Memory Provider（替换临时 :memory:，方案 §10/§12）。云端应经
+        # LongTermMemoryService/HTTP/SDK Provider；本地默认 SQLite 文件库。
+        provider = resolve_default_memory_provider()
+        coordinator = MemoryCoordinator(provider)
+        from ksadk.memory.coordinator import agent_user_scope_id
+
+        _scope_id = agent_user_scope_id(agent_id=agent_id, user_id=str(user_id or ""))
+        candidates = propose_memory_candidates(list(events), scope="user", scope_id=_scope_id)
+        if not candidates:
+            return {"status": "skipped", "proposed": 0, "committed": 0, "rejected": 0}
+        result = coordinator.flush_candidates(candidates)
+        return result.to_audit_dict()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("memory flush failed: %s", exc)
+        return {"status": "failed", "error": str(exc), "proposed": 0, "committed": 0, "rejected": 0}
+
+
 async def compact_conversation_history(
     *,
     session_id: str,
@@ -228,21 +365,29 @@ async def compact_conversation_history(
     trigger: str = "auto",
     keep_tail_groups: Optional[int] = None,
     session_service_provider: Callable[[], Any] | None = None,
+    prompt_integration_mode: str = "",
+    compaction_owner: str = "",
 ) -> SessionEvent | None:
     """把旧轮次折叠为 checkpoint。
 
     这是本地版的 compaction：先按 API round 分组，再保留尾部若干轮，把更早
     的部分压成 append-only summary 事件。force=True 时用于 PTL 恢复。
+
+    compaction_owner 硬门控（方案 §6.2）：非 ksadk 时不走 KsADK 双阈值压缩。
     """
     provider = session_service_provider or resolve_session_service
     service = provider()
     events = await service.get_events(session_id)
+    session = await service.get_session(session_id)
+    memory_user_id = str(getattr(session, "user_id", "") or "")
     plan = _plan_compaction(
         events,
         model=model,
         model_metadata=model_metadata,
         force=force,
         keep_tail_groups=keep_tail_groups,
+        prompt_integration_mode=prompt_integration_mode,
+        compaction_owner=compaction_owner,
     )
     if not plan.should_compact:
         return None
@@ -285,7 +430,38 @@ async def compact_conversation_history(
     # L5 working set 恢复(保守版):只记 metadata,不读文件内容。
     working_set = build_working_set_metadata(pinned_state=plan.pinned_state)
 
-    return await append_context_checkpoint_event(
+    # PR D2：Session Working State（仅 ksadk_hosted）。从事实事件确定性提取，
+    # 写进 checkpoint metadata 供下一轮门控重注入。非门控不写（向后兼容）。
+    working_state_audit: dict[str, Any] | None = None
+    # PR D2.5：Memory Flush（方案 §9.2）。仅 ksadk_hosted + policy 开启时，压缩前 best-effort
+    # 提取候选并提交；失败不阻止 compaction（§9.2 失败语义）。非门控不执行（向后兼容）。
+    memory_flush_audit: dict[str, Any] | None = None
+    if (
+        compaction_owner == "ksadk"
+        or (not compaction_owner and prompt_integration_mode == "ksadk_hosted")
+    ) and plan.groups_to_compact:
+        compacted_events = [event for group in plan.groups_to_compact for event in group]
+        seq_range = (
+            int(plan.groups_to_compact[0][0].seq_id or 0),
+            int(plan.groups_to_compact[-1][-1].seq_id or 0),
+        )
+        working_state = extract_working_state(
+            compacted_events,
+            pinned_state=plan.pinned_state,
+            summary_text=summary_result.summary_text,
+            source_seq_range=seq_range,
+        )
+        # §8.1：关键字段缺失时用压缩前 checkpoint 的 WorkingState 合并，不接受空值覆盖。
+        previous_ws = _working_state_from_checkpoint(latest_checkpoint)
+        working_state.merge_missing_from(previous_ws)
+        working_state_audit = working_state.to_audit_dict()
+        memory_flush_audit = await _maybe_memory_flush(
+            compacted_events, user_id=memory_user_id, agent_id=author
+        )
+
+    # PR D2.6：per-session compaction lock + stale guard（方案 §9.6）。同一 session 同时只
+    # 允许一个 checkpoint/WorkingState 提交；拿不到锁则放弃本次提交避免并发覆盖。
+    _checkpoint_kwargs = dict(
         session_id=session_id,
         author=author,
         compacted_until_seq_id=compacted_until_seq_id_value,
@@ -328,6 +504,32 @@ async def compact_conversation_history(
                 else None
             ),
             "working_set": working_set,
+            # PR D1：双阈值带标记（""=非门控旧路径 / "soft" / "hard" / "emergency"=PTL）。
+            # 仅审计用，不改变既有 trigger 字段；trigger 仍为调用方值。
+            "trigger_band": plan.trigger_band,
+            # PR D2：Session Working State（仅 ksadk_hosted）。结构化工作面，供下一轮门控重注入。
+            # 含 content_hash/source_seq_range/status，无 prompt 明文。非门控不写该键（向后兼容）。
+            **({"working_state": working_state_audit} if working_state_audit is not None else {}),
+            # PR D2.5：Memory Flush 审计（方案 §9.2）。失败不阻止 compaction。
+            **({"memory_flush": memory_flush_audit} if memory_flush_audit is not None else {}),
+            # PR D2：tokens_by_kind before/after（从 pipeline stats 取，审计用）。
+            "tokens_by_kind_before": {"transcript": pipeline_result["tokens_before"]},
+            "tokens_by_kind_after": {"transcript": pipeline_result["tokens_after"]},
         },
         session_service_provider=provider,
     )
+    try:
+        from ksadk.conversations.session_lock import session_compaction_lock
+    except Exception:  # noqa: BLE001
+        session_compaction_lock = None  # type: ignore[assignment]
+    if session_compaction_lock is None:
+        return await append_context_checkpoint_event(**_checkpoint_kwargs)
+    try:
+        async with session_compaction_lock(session_id):
+            return await append_context_checkpoint_event(**_checkpoint_kwargs)
+    except asyncio.TimeoutError:
+        logger.warning(
+            "session compaction lock timeout for %s; skipping checkpoint commit",
+            session_id,
+        )
+        return None

ksadk/conversations/runtime_input.py

@@ -48,6 +48,74 @@ def _env_flag(name: str, default: bool = True) -> bool:
     return normalized not in {"0", "false", "no", "off"}
 
 
+def _prompt_compiler_enabled() -> bool:
+    """PR B：全局 kill switch。默认关——关闭时 Runner 输入与旧逻辑字节级一致。
+
+    接管由三重门控共同决定：本 flag × per-Agent ``prompt_integration_mode``
+    （由 ``prompt_ownership=ksadk`` 标记的 per-Build）× runner 类型限定 LangGraph。
+    任一不满足 → ``_should_project_compiled_prompt`` 返回 False → 走旧 ``instructions`` 分支。
+    """
+    return _env_flag("KSADK_PROMPT_COMPILER_ENABLED", False)
+
+
+def _should_project_compiled_prompt(
+    *, prepared: PreparedConversationTurn, runner: Any | None
+) -> bool:
+    """PR B：判断本 turn 是否用 ``compiled_prompt`` 接管 ``payload["instructions"]``。
+
+    满足全部条件才接管：
+    1. 全局 flag 开（``KSADK_PROMPT_COMPILER_ENABLED``）；
+    2. per-Build 接管标记 ``prompt_integration_mode=="ksadk_hosted"``
+       （仅 ``prompt_ownership=ksadk``）；
+    3. 已编译出真实 CompiledPrompt 且含非空 ``prompt_content``（agent_system/agent_task 非空，
+       非 resume 旁路）；
+    4. runner 类型为 langgraph（ADK/Codex 接管错位，排除）。
+
+    任一不满足 → 返回 False → 调用方走 ``elif`` 分支 == 旧 ``if``，字节级一致。
+    """
+    if not _prompt_compiler_enabled():
+        return False
+    if prepared.prompt_integration_mode != "ksadk_hosted":
+        return False
+    compiled = prepared.compiled_prompt
+    if not isinstance(compiled, Mapping):
+        return False
+    content = compiled.get("prompt_content")
+    if not isinstance(content, str) or not content.strip():
+        return False
+    return _runner_type_name(runner) == "langgraph"
+
+
+def _should_use_hosted_assembly(*, prepared: PreparedConversationTurn, runner: Any | None) -> bool:
+    """PR E：判断本 turn 是否用 hosted pipeline 的 assembled_input 接管 payload。
+
+    条件：``assembled_input`` 已生成（build_run_input 在 V2 门控下产出）且 runner 为
+    langgraph 系（prompt_owner=ksadk）。该分支优先于 PR B/D2；满足时直接 return，不双重注入。
+    native_runtime（codex）的 ``assembled_input`` 恒为 None（build_run_input 不为它生成），
+    故 Managed Codex 不受影响（方案 §6.2 / PCM-RUNNER-003）。
+    """
+    if not isinstance(prepared.assembled_input, Mapping):
+        return False
+    if not str(prepared.assembled_input.get("system") or "").strip():
+        return False
+    return _runner_type_name(runner) == "langgraph"
+
+
+def _assembled_input(prepared: PreparedConversationTurn) -> Any:
+    """把 prepared.assembled_input 的 plain dict 还原成 assembler 能消费的形式。"""
+    from ksadk.context_engine.assembler import AssembledInput
+
+    d = prepared.assembled_input
+    return AssembledInput(
+        format=d.get("format", "chat"),
+        system=str(d.get("system") or ""),
+        messages=list(d.get("messages") or []),
+        responses_items=[],
+        estimated_tokens=int(d.get("estimated_tokens") or 0),
+        warnings=tuple(d.get("warnings") or ()),
+    )
+
+
 def _ltm_auto_save_enabled() -> bool:
     backend = str(os.getenv("KSADK_LTM_BACKEND") or "").strip().lower()
     namespace = str(os.getenv("KSADK_LTM_NAMESPACE") or "").strip()
@@ -83,10 +151,19 @@ def _ambient_context_has_error(context: Any) -> bool:
     if not isinstance(context, dict):
         return True
 
+    # 显式 error 字段（PR：Memory Recall 失败语义）：build_context 失败时把原因放
+    # 独立 ``error`` 字段、``formatted_text`` 置空，错误不进模型上下文。
+    if str(context.get("error") or "").strip():
+        return True
+
     formatted_text = str(context.get("formatted_text") or "").strip()
+    # 真无记忆不是可注入的上下文。它不是 provider failure，但对投影层而言
+    # 同样应被丢弃，避免 UI 和审计把空召回误报成“已使用长期记忆”。
     if not formatted_text:
         return True
 
+    # 纵深防御：``search_text``（工具路径）仍会把错误塞进正文，这里按前缀兜底，
+    # 防止任何直接调 ``search_text`` 拼上下文的路径把错误字符串注入。
     failure_prefixes = (
         "知识库检索失败",
         "长期记忆检索失败",
@@ -350,6 +427,7 @@ def _build_runner_ambient_contexts(
     contexts: dict[str, Any] = {
         "kb_context": None,
         "memory_context": None,
+        "memory_recall_events": [],
     }
     normalized_input = str(user_input or "").strip()
     if not normalized_input or not _should_use_platform_ambient_context(runner):
@@ -379,8 +457,18 @@ def _build_runner_ambient_contexts(
             )
             if not _ambient_context_has_error(memory_context):
                 contexts["memory_context"] = memory_context
+                contexts.setdefault("memory_recall_events", []).append(
+                    {"type": "memory.recall.completed", "count": 1}
+                )
+            else:
+                contexts.setdefault("memory_recall_events", []).append(
+                    {"type": "memory.recall.empty"}
+                )
         except Exception as exc:
             logger.warning("Failed to build ambient memory context: %s", exc)
+            contexts.setdefault("memory_recall_events", []).append(
+                {"type": "memory.recall.failed", "error": str(exc)[:200]}
+            )
 
     return contexts
 
@@ -417,7 +505,31 @@ def _build_runner_request_payload(
         # (for example, its conversation approval profile) without leaking
         # caller public metadata into the agent payload.
         payload["request_metadata"] = dict(prepared.request_metadata)
-    if prepared.instructions:
+    # PR E：hosted pipeline 接管（最高优先级）。当 build_run_input 产出 assembled_input 时，
+    # 用组装好的 system/input/history 直接覆盖 payload——它已含 compiled_prompt + working_state
+    # + planner 决策后的有序 messages。此分支满足后不再走 PR B/D2（避免双重注入）。
+    if _should_use_hosted_assembly(prepared=prepared, runner=runner):
+        from ksadk.context_engine.hosted_pipeline import assembled_to_payload
+
+        override = assembled_to_payload(_assembled_input(prepared))
+        if override["instructions"]:
+            payload["instructions"] = override["instructions"]
+        if override["input"]:
+            payload["input"] = override["input"]
+        # An empty assembled history is authoritative: on the first turn the
+        # just-persisted user event must not survive from ``prepared.history``
+        # and be injected alongside the canonical current input.
+        payload["history"] = override["history"]
+        payload["context_plan_id"] = (
+            prepared.context_plan.get("plan_id") if prepared.context_plan else None
+        )
+        return payload
+    # PR B：LangGraph CompiledPrompt→instructions 接管。三重门控满足时，把
+    # payload["instructions"] 替换为 CompiledPrompt.content（XML），使 agent_system/
+    # agent_task 首次进模型输入。任一门控不满足 → elif == 旧逻辑（字节级一致）。
+    if _should_project_compiled_prompt(prepared=prepared, runner=runner):
+        payload["instructions"] = prepared.compiled_prompt["prompt_content"]
+    elif prepared.instructions:
         payload["instructions"] = prepared.instructions
     if prepared.resume_input is not None:
         if _is_checkpoint_resume_input(prepared.resume_input):
@@ -431,7 +543,15 @@ def _build_runner_request_payload(
                 prepared.resume_input.get("checkpoint_metadata") or {}
             )
         else:
-            payload["input"] = prepared.resume_input
+            resume_input = dict(prepared.resume_input)
+            gateway_approval_resume = bool(
+                resume_input.pop("_ksadk_gateway_approval_resume", False)
+            )
+            if gateway_approval_resume and bool(
+                getattr(runner, "supports_gateway_approval_semantic_resume", False)
+            ):
+                resume_input["_ksadk_gateway_approval_resume"] = True
+            payload["input"] = resume_input
             payload["resume"] = True
     previous_response_id = prepared.request_metadata.get("previous_response_id")
     if previous_response_id:
@@ -446,9 +566,74 @@ def _build_runner_request_payload(
     deferred_tool_names = _extract_deferred_tool_names(prepared.request_metadata)
     if deferred_tool_names:
         payload["deferred_tool_names"] = deferred_tool_names
+    # PR D2：WorkingState 门控重注入。仅 ksadk_hosted + 有 working_state 时，把结构化工作面
+    # 渲染成 XML 段追加进 instructions（与 CompiledPrompt.content 风格一致，LangGraph _to_state
+    # 能消费 instructions 字符串）。非门控或有 CompiledPrompt 接管时仍由前者决定 instructions。
+    _maybe_inject_working_state(payload, prepared)
     return payload
 
 
+def _maybe_inject_working_state(
+    payload: dict[str, Any], prepared: PreparedConversationTurn
+) -> None:
+    """PR D2：把 working_state 渲染成 <working_state> XML 段追加进 payload instructions。
+
+    门控：仅 ``prompt_integration_mode=="ksadk_hosted"`` 且 ``working_state`` 非空时注入。
+    与 PR B 的 CompiledPrompt 接管叠加：若 instructions 已被 CompiledPrompt 接管（XML），
+    WorkingState 段追加在其后；否则追加在 request instructions 后。非门控零注入。
+    Prompt 明文不进 Trace（working_state 不进 shadow plan/trace）。
+    """
+    if prepared.prompt_integration_mode != "ksadk_hosted":
+        return
+    ws = prepared.working_state
+    if not isinstance(ws, Mapping) or not ws:
+        return
+    xml = _render_working_state_xml(ws)
+    if not xml:
+        return
+    existing = str(payload.get("instructions") or "").strip()
+    if existing:
+        payload["instructions"] = f"{existing}\n\n{xml}"
+    else:
+        payload["instructions"] = xml
+
+
+def _render_working_state_xml(ws: Mapping[str, Any]) -> str:
+    """把 working_state 审计 dict 渲染成 <working_state> XML 段（供模型理解当前工作面）。"""
+    current_goal = str(ws.get("current_goal") or "").strip()
+    next_action = str(ws.get("next_action") or "").strip()
+    active_files = ws.get("active_files") or []
+    pending_tools = ws.get("pending_tools") or []
+    pending_approvals = ws.get("pending_approvals") or []
+    lines: list[str] = []
+    if current_goal:
+        lines.append(f"当前目标：{current_goal}")
+    if next_action:
+        lines.append(f"下一步：{next_action}")
+    if isinstance(active_files, list) and active_files:
+        files = ", ".join(
+            str((f.get("path") if isinstance(f, Mapping) else "") or "") for f in active_files
+        ).strip(", ")
+        if files:
+            lines.append(f"活跃文件：{files}")
+    if isinstance(pending_tools, list) and pending_tools:
+        tools = "; ".join(
+            str((t.get("text") if isinstance(t, Mapping) else "") or "") for t in pending_tools
+        ).strip("; ")
+        if tools:
+            lines.append(f"未完成工具：{tools}")
+    if isinstance(pending_approvals, list) and pending_approvals:
+        approvals = "; ".join(
+            str((a.get("text") if isinstance(a, Mapping) else "") or "") for a in pending_approvals
+        ).strip("; ")
+        if approvals:
+            lines.append(f"待审批：{approvals}")
+    if not lines:
+        return ""
+    body = "\n".join(lines)
+    return f"<working_state>\n{body}\n</working_state>"
+
+
 def _inject_runner_deferred_tools_for_request(
     runner: Any, prepared: PreparedConversationTurn
 ) -> None:
@@ -563,7 +748,12 @@ async def _auto_save_ltm_turn(
     runner_type: str,
     model: str | None,
 ) -> None:
-    if prepared.resume_input is not None or not _ltm_auto_save_enabled():
+    if prepared.resume_input is not None:
+        return
+    memory_rollout = str(prepared.memory_write_rollout or "").strip().lower()
+    if memory_rollout in {"off", "shadow"}:
+        return
+    if not memory_rollout and not _ltm_auto_save_enabled():
         return
 
     metadata: dict[str, Any] = {