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

ksadk/runtime/factory.py

@@ -0,0 +1,342 @@
+"""内置 RuntimeAdapter 的唯一默认 Factory Registry。"""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from ksadk.codex.client import AsyncCodexClient
+from ksadk.codex.runtime import CodexRuntimeAdapter
+from ksadk.runners.base_runner import BaseRunner
+from ksadk.runtime.adapter import StartRequest
+from ksadk.runtime.adapter import RuntimeAdapter, RuntimeRegistry
+from ksadk.runtime.framework_adapters import ADKRuntimeAdapter, LangGraphRuntimeAdapter
+from ksadk.runtime.launch import RuntimeLaunchContext
+
+
+def kernel_start_request_defaults(context: RuntimeLaunchContext) -> dict[str, Any]:
+    """Project an admitted launch manifest into immutable Kernel turn defaults.
+
+    The durable Kernel owns enqueue ordering, while the deployment manifest
+    owns model, instructions, sandbox and approval policy.  Keeping this
+    projection beside the RuntimeAdapter factory prevents the Kernel ingress
+    from trusting caller-supplied execution policy.
+    """
+
+    config = dict(context.config)
+    defaults: dict[str, Any] = {}
+    detection_name = str(getattr(context.detection, "name", "") or "").strip()
+    if detection_name:
+        defaults["agent_id"] = detection_name
+    model = str(config.get("model") or "").strip()
+    if model:
+        defaults["model"] = model
+    raw_allowed_models = (
+        config.get("models") or config.get("allowed_models") or config.get("allowedModels") or []
+    )
+    allowed_models = (
+        {str(item).strip() for item in raw_allowed_models if str(item).strip()}
+        if isinstance(raw_allowed_models, (list, tuple, set))
+        else set()
+    )
+    # 不把默认 model 自动加进白名单:白名单只在显式声明 models/allowedModels
+    # 时才存在(显式声明 = 收紧;只配默认 = 不限制 run 级覆盖)。
+    if allowed_models:
+        defaults["allowed_models"] = sorted(allowed_models)
+    if context.runtime_type != "codex":
+        return defaults
+
+    prompt = str(config.get("prompt") or "").strip()
+    task_prompt = str(config.get("task_prompt") or "").strip()
+    base_instructions = prompt
+    if task_prompt:
+        base_instructions = f"{prompt}\n\n{task_prompt}" if prompt else task_prompt
+
+    raw_sandbox = str(config.get("sandbox") or "read_only").strip().lower()
+    raw_approval = str(config.get("approval_mode") or "").strip().lower()
+    approval_profiles = {
+        "ask": ("workspace-write", "manual"),
+        "risk": ("workspace-write", "auto_review"),
+        "full": ("full-access", "deny_all"),
+    }
+    sandbox_profiles = {
+        "read_only": ("read-only", "deny_all"),
+        "read-only": ("read-only", "deny_all"),
+        "workspace_write": ("workspace-write", "deny_all"),
+        "workspace-write": ("workspace-write", "deny_all"),
+        "workspace_write_auto": ("workspace-write", "auto_review"),
+        "workspace-write-auto": ("workspace-write", "auto_review"),
+        "full_access": ("full-access", "deny_all"),
+        "full-access": ("full-access", "deny_all"),
+    }
+    if raw_approval in approval_profiles:
+        sandbox, approval = approval_profiles[raw_approval]
+    else:
+        sandbox, default_approval = sandbox_profiles.get(raw_sandbox, ("read-only", "deny_all"))
+        approval = raw_approval or default_approval
+
+    request_config: dict[str, Any] = {
+        "sandbox_read_only": sandbox == "read-only",
+        "sandbox": sandbox,
+        "approval_mode": approval,
+        "cwd": str(context.project_dir),
+        "summary": "auto",
+        "ephemeral": False,
+    }
+    if base_instructions:
+        request_config["base_instructions"] = base_instructions
+    defaults["config"] = request_config
+    return defaults
+
+
+def apply_runtime_start_request_defaults(
+    context: RuntimeLaunchContext,
+    request: StartRequest,
+) -> StartRequest:
+    """Apply deployment-owned launch policy to a direct runtime start.
+
+    AgentKernelWorker already projects these defaults before ``adapter.start``.
+    Foreground RunAgent, ``/run_sse`` and OpenAI-compatible routes also create
+    ``StartRequest`` objects directly, so they must use the same projection or
+    a deployed Codex agent silently falls back to the generic Codex role.
+
+    Request-local config is internal runtime state, not caller-owned policy;
+    retain it for local Studio builds while using the manifest model as the
+    fallback (and as the fail-closed fallback for an explicit allow-list).
+    """
+
+    defaults = kernel_start_request_defaults(context)
+    default_model = str(defaults.get("model") or "").strip() or None
+    requested_model = str(request.model or "").strip()
+    allowed_models = {
+        str(item).strip()
+        for item in (defaults.get("allowed_models") or [])
+        if str(item).strip()
+    }
+    selected_model = (
+        requested_model
+        if requested_model and (not allowed_models or requested_model in allowed_models)
+        else default_model
+    )
+    config = {
+        **dict(defaults.get("config") or {}),
+        **dict(request.config or {}),
+    }
+    return request.model_copy(
+        update={
+            "agent_id": request.agent_id or defaults.get("agent_id"),
+            "model": selected_model,
+            "config": config,
+        }
+    )
+
+
+def _manifest_mcp_overrides(config: dict[str, Any]) -> list[str]:
+    """Translate declarative MCP bindings into native Codex config keys."""
+
+    overrides: list[str] = []
+    servers = config.get("mcp_servers") or []
+    if not isinstance(servers, (list, tuple)):
+        return overrides
+    for server in servers:
+        if not isinstance(server, dict):
+            continue
+        name = str(server.get("name") or "").strip()
+        url = str(server.get("url") or "").strip()
+        if not name or not url:
+            continue
+        overrides.append(f"mcp_servers.{name}.url={url}")
+        env_key = str(server.get("env_key") or "").strip()
+        if env_key:
+            overrides.append(f"mcp_servers.{name}.bearer_token_env_var={env_key}")
+    return overrides
+
+
+def _create_codex(context: RuntimeLaunchContext) -> RuntimeAdapter:
+    client_factory = context.services.codex_client_factory or AsyncCodexClient
+    config = dict(context.config)
+    overrides = list(config.get("codex_overrides") or [])
+    manifest_mcp_overrides = _manifest_mcp_overrides(config)
+    overrides.extend(item for item in manifest_mcp_overrides if item not in overrides)
+    projected_config = kernel_start_request_defaults(context).get("config") or {}
+    if manifest_mcp_overrides and projected_config.get("sandbox") == "workspace-write":
+        network_override = "sandbox_workspace_write.network_access=true"
+        if network_override not in overrides:
+            overrides.append(network_override)
+    # Studio's default collaboration mode must expose Codex's structured
+    # request_user_input tool; the upstream feature is intentionally off by
+    # default outside Plan mode.  This stays process-local to the isolated
+    # runtime and does not mutate the user's global Codex configuration.
+    interaction_override = "features.default_mode_request_user_input=true"
+    if interaction_override not in overrides:
+        overrides.append(interaction_override)
+    try:
+        from openai_codex import CodexConfig
+
+        base_cfg = CodexConfig()
+        if overrides:
+            base_cfg = dataclasses.replace(
+                base_cfg,
+                config_overrides=tuple(getattr(base_cfg, "config_overrides", ()) or ())
+                + tuple(str(o) for o in overrides),
+            )
+        env = dict(getattr(base_cfg, "env", None) or {})
+        isolated_home = _isolated_codex_home(context.project_dir)
+        env.setdefault("CODEX_HOME", str(isolated_home))
+        # HOME 级隔离：codex app-server 还会按约定扫 ~/.agents/skills、
+        # ~/.claude/skills 等宿主目录，仅设 CODEX_HOME 挡不住。隔离 HOME 后这些
+        # 路径全部落在工作区内，宿主 skills/MCP/凭证不再进入 Agent 上下文。
+        # 设 KSADK_CODEX_ISOLATE_HOME=0 可关闭（调试用）。
+        if os.environ.get("KSADK_CODEX_ISOLATE_HOME", "1") != "0":
+            env.setdefault("HOME", str(isolated_home))
+        # 运行期解析出的凭证值（如 MCP bearer_token_env_var 所需）注入子进程环境
+        env.update({str(k): str(v) for k, v in (context.config.get("env") or {}).items()})
+        base_cfg = dataclasses.replace(base_cfg, env=env)
+        try:
+            client: Any = client_factory(config=base_cfg)
+        except TypeError:
+            # 自定义/测试工厂可能不接受 config 参数：退化为无参构造，
+            # config_overrides 事后注入（自定义工厂自行承担 env 隔离）。
+            client = client_factory()
+            if overrides:
+                _apply_codex_overrides(client, overrides)
+    except ImportError:
+        client: Any = client_factory()
+        if overrides:
+            _apply_codex_overrides(client, overrides)
+    timeout = context.config.get("turn_timeout_seconds")
+    request_defaults = kernel_start_request_defaults(context)
+    request_config = request_defaults.get("config") or {}
+    sandbox_read_only = (
+        bool(context.config["sandbox_read_only"])
+        if "sandbox_read_only" in context.config
+        else bool(request_config.get("sandbox_read_only", True))
+    )
+    return CodexRuntimeAdapter(
+        client,
+        sandbox_read_only=sandbox_read_only,
+        turn_timeout_seconds=float(timeout) if timeout is not None else None,
+    )
+
+
+def _isolated_codex_home(project_dir: Any) -> Path:
+    """Studio 运行 Agent 使用工作区级隔离 CODEX_HOME。
+
+    避免 codex app-server 继承宿主环境（~/.codex / ~/.wework/codex）里的
+    skills、MCP 配置、插件与凭证，污染 Agent 上下文甚至泄漏宿主能力。
+    可用 KSADK_CODEX_HOME 显式覆盖。
+    """
+    override = os.environ.get("KSADK_CODEX_HOME")
+    if override:
+        home = Path(override).expanduser()
+        home.mkdir(parents=True, exist_ok=True)
+        return home
+
+    # Source bundles are deliberately mounted read-only in managed runtimes.
+    # Keep the preferred workspace-local isolation for local development, but
+    # never make a Codex turn depend on being able to mutate that bundle.
+    workspace_home = Path(str(project_dir)) / ".agentkit" / "codex-home"
+    try:
+        workspace_home.mkdir(parents=True, exist_ok=True)
+        return workspace_home
+    except OSError:
+        pass
+
+    # The managed runtime already provides a per-workload writable state
+    # volume.  Derive from its explicit directory first, then from the
+    # session-store path for backward-compatible images.  /tmp is a final
+    # process-local fallback for custom read-only launchers.
+    state_dir = os.environ.get("KSADK_RUNTIME_STATE_DIR")
+    session_path = os.environ.get("KSADK_SESSION_PATH")
+    fallback_root = (
+        Path(state_dir)
+        if state_dir
+        else Path(session_path).expanduser().parent
+        if session_path
+        else Path(tempfile.gettempdir()) / "ksadk-runtime-state"
+    )
+    fallback_home = fallback_root / "codex-home"
+    fallback_home.mkdir(parents=True, exist_ok=True)
+    return fallback_home
+
+
+def _apply_codex_overrides(client: Any, overrides: Any) -> None:
+    """Append MCP server --config overrides to the client's CodexConfig."""
+    try:
+        from openai_codex import CodexConfig
+    except ImportError:
+        return
+    # ksadk AsyncCodexClient -> AsyncCodex -> inner AsyncCodexClient.config
+    inner_codex = getattr(client, "_codex", None)
+    inner_client = getattr(inner_codex, "_client", None) or inner_codex
+    cfg = getattr(inner_client, "config", None)
+    if cfg is None or not isinstance(cfg, CodexConfig):
+        return
+    base_overrides = tuple(getattr(cfg, "config_overrides", ()) or ())
+    new_overrides = tuple(str(o) for o in overrides if o not in base_overrides)
+    if not new_overrides:
+        return
+    new_cfg = dataclasses.replace(cfg, config_overrides=base_overrides + new_overrides)
+    setattr(inner_client, "config", new_cfg)
+
+
+def _create_framework_runner(context: RuntimeLaunchContext, runtime_type: str) -> BaseRunner:
+    try:
+        from ksadk.runners.patch_langchain import apply_patch
+
+        apply_patch()
+    except ImportError:
+        pass
+    detection = context.detection
+    if detection is None:
+        raise ValueError(f"{runtime_type} runtime requires framework detection")
+    if context.services.runner_factory is not None:
+        runner = context.services.runner_factory(detection, str(context.project_dir))
+    else:
+        # 复用 runners.factory.create_runner:它优先读 detection.runner_class
+        # (agentengine.yaml 的 runner_class 字段),否则按 detection.type 分发到
+        # ADKRunner/LangGraphRunner 等。直接硬编码 LangGraphRunner 会绕过自定义
+        # runner,导致 root_agent=None 的项目在 preflight 阶段误报"不是有效 CompiledGraph"。
+        from ksadk.runners.factory import create_runner
+
+        runner = create_runner(detection, str(context.project_dir))
+    if not isinstance(runner, BaseRunner):
+        raise TypeError(
+            f"{runtime_type} runner factory must return BaseRunner, got {type(runner).__name__}"
+        )
+    return runner
+
+
+def _create_adk(context: RuntimeLaunchContext) -> RuntimeAdapter:
+    return ADKRuntimeAdapter(_create_framework_runner(context, "adk"))
+
+
+def _create_langgraph(context: RuntimeLaunchContext) -> RuntimeAdapter:
+    return LangGraphRuntimeAdapter(_create_framework_runner(context, "langgraph"))
+
+
+def build_default_runtime_registry() -> RuntimeRegistry:
+    """注册内置 Codex、ADK 和 LangGraph Runtime Factory。"""
+
+    registry = RuntimeRegistry()
+    registry.register("codex", _create_codex)
+    registry.register("adk", _create_adk)
+    registry.register("langgraph", _create_langgraph)
+    return registry
+
+
+def create_runtime_adapter(context: RuntimeLaunchContext) -> RuntimeAdapter:
+    """通过唯一默认 Registry 创建 RuntimeAdapter。"""
+
+    return build_default_runtime_registry().create(context)
+
+
+__all__ = [
+    "apply_runtime_start_request_defaults",
+    "build_default_runtime_registry",
+    "create_runtime_adapter",
+    "kernel_start_request_defaults",
+]

ksadk/runtime/framework_adapters.py

@@ -6,7 +6,7 @@
 - ADK:**forward-only**,resume 经 ``invocation_id``;不支持 time-travel/fork。
 - LangGraph:**time-travel**,resume 经 ``checkpoint_id``;可按 turn 回滚/fork。
 
-并用 :func:`build_default_registry` 注册进 G0.3 ``RuntimeRegistry``。
+默认注册由 :mod:`ksadk.runtime.factory` 统一负责。
 """
 
 from __future__ import annotations
@@ -19,7 +19,6 @@ from ksadk.runtime.adapter import (
     ResumePayload,
     ResumeTarget,
     RunHandle,
-    RuntimeRegistry,
 )
 from ksadk.runtime.runner_adapter import RunnerRuntimeAdapter
 
@@ -88,10 +87,14 @@ class LangGraphRuntimeAdapter(RunnerRuntimeAdapter):
         # ``checkpoint_resume`` + ``framework_ref.langgraph.{checkpoint_id,thread_id}``。
         return {
             "checkpoint_resume": True,
+            "run_id": handle.run_id,
             "resume_payload_provided": payload is not None,
             "resume_interrupt_id": payload.call_id if payload else None,
             "framework_ref": {
-                "langgraph": {"checkpoint_id": target.id, "thread_id": handle.session_id}
+                "langgraph": {
+                    "checkpoint_id": target.id,
+                    "thread_id": str(handle.native_ref.get("thread_id") or handle.session_id),
+                }
             },
             "input": payload.data if payload else None,
         }
@@ -109,16 +112,7 @@ class LangGraphRuntimeAdapter(RunnerRuntimeAdapter):
         )
 
 
-def build_default_registry() -> RuntimeRegistry:
-    """构造默认 RuntimeRegistry 并注册 ADK/LangGraph adapter 类型。"""
-    registry = RuntimeRegistry()
-    registry.register("adk", ADKRuntimeAdapter)
-    registry.register("langgraph", LangGraphRuntimeAdapter)
-    return registry
-
-
 __all__ = [
     "ADKRuntimeAdapter",
     "LangGraphRuntimeAdapter",
-    "build_default_registry",
 ]

ksadk/runtime/hosted_finalizer.py

@@ -0,0 +1,268 @@
+"""HostedTurnFinalizer —— 统一 Studio 与 canonical Runtime 的 turn 收尾（方案 §11.1 / P0）。
+
+之前 Studio `StudioRunService` 和 canonical `conversation_execution._finalize_hosted_turn`
+各自维护一套收尾逻辑（usage 回填、Context evidence、Memory Candidate、Trace），导致两条路径
+漂移（如 scope_id 硬编码 local-user、Memory 重复写）。本组件统一负责：
+
+- actual usage 回填进 ContextPlan（planned vs actual 偏差可观测）。
+- capability mismatch 证据检测（方案 §6.1）。
+- Memory Candidate 抽取 + flush（据 MemoryPolicy，同一 Turn 不重复写）。
+- 失败降级（best-effort，绝不阻断主链路，方案 §10.8）。
+
+Studio 与 canonical Runtime 都调用本组件，不再各自实现收尾。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping
+
+
+def _memory_extract_enabled() -> bool:
+    return str(os.environ.get("KSADK_MEMORY_FLUSH_ENABLED", "")).strip().lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+
+
+def _extract_input_tokens(usage: Mapping[str, Any] | None) -> int | None:
+    """从 runtime usage 取 input tokens（兼容 OpenAI/Anthropic 字段）。"""
+    if not isinstance(usage, Mapping):
+        return None
+    for key in ("input_tokens", "prompt_tokens", "input_token_count"):
+        v = usage.get(key)
+        if isinstance(v, (int, float)) and v:
+            return int(v)
+    details = usage.get("input_token_details") or usage.get("input_tokens_details")
+    if isinstance(details, Mapping):
+        total = details.get("total") or details.get("input_tokens")
+        if isinstance(total, (int, float)) and total:
+            return int(total)
+    return None
+
+
+@dataclass(frozen=True)
+class FinalizeContext:
+    """turn 收尾所需的上下文（Studio 与 canonical 共用）。"""
+
+    session_id: str
+    invocation_id: str
+    user_id: str
+    context_plan: dict[str, Any] | None
+    shadow_context_plan: dict[str, Any] | None
+    usage: Mapping[str, Any] | None
+    runtime_type: str
+    agent_id: str = ""
+    prompt_integration_mode: str = ""
+    session_events: Any = None  # 已取的 turn events（避免重复读 store）
+    memory_write_rollout: str = ""
+    memory_enabled: bool | None = None
+    memory_recall_enabled: bool | None = None
+    memory_write_mode: str = "candidate"
+    flush_before_compaction: bool = True
+    provider_ref: str = "local-default"
+    emit_event: Any = None
+
+
+async def finalize_hosted_turn(
+    ctx: FinalizeContext,
+    *,
+    session_service_provider: Callable[[], Any] | None = None,
+) -> None:
+    """统一 hosted turn 收尾（方案 §11.1 步骤 15-16 / P0 收敛）。
+
+    Studio 与 canonical Runtime 都调用本函数，不再各自实现。失败不阻断主链路。
+    """
+    # 1. usage 回填进 ContextPlan
+    plan = ctx.context_plan
+    if isinstance(plan, dict):
+        try:
+            actual = _extract_input_tokens(ctx.usage)
+            if actual is not None:
+                plan["runtime_reported_input_tokens"] = actual
+        except Exception:  # noqa: BLE001
+            pass
+
+    # 2. capability mismatch 证据检测
+    try:
+        _maybe_detect_capability_mismatch(ctx)
+    except Exception:  # noqa: BLE001
+        pass
+
+    # 3. Memory Candidate 抽取 + flush
+    # 统一解析 Memory 运行策略（方案 §2：ResolvedMemoryPolicy 统一入口）
+    from ksadk.memory.resolved_policy import resolve_memory_policy
+
+    policy = resolve_memory_policy(
+        memory_enabled=ctx.memory_enabled,
+        recall_enabled=ctx.memory_recall_enabled,
+        write_rollout=ctx.memory_write_rollout,
+        write_mode=ctx.memory_write_mode,
+        flush_before_compaction=ctx.flush_before_compaction,
+        provider_ref=ctx.provider_ref,
+    )
+    # shadow：生成 Candidate 和审计事件，但不提交 Provider（方案 §2）
+    # off/不启用：直接返回，连候选都不提取
+    if not policy.should_extract_candidates:
+        return
+    try:
+        from ksadk.memory.coordinator import MemoryCoordinator
+        from ksadk.memory.events import (
+            candidate_created,
+            candidate_rejected,
+            flush_completed,
+            flush_failed,
+        )
+        from ksadk.memory.extraction import propose_memory_candidates
+        from ksadk.memory.provider_resolver import resolve_memory_provider
+
+        turn_events = ctx.session_events
+        if turn_events is None and session_service_provider is not None:
+            try:
+                service = session_service_provider()
+                all_events = await service.get_events(ctx.session_id)
+                turn_events = [
+                    e for e in all_events if getattr(e, "invocation_id", "") == ctx.invocation_id
+                ]
+            except Exception:  # noqa: BLE001
+                turn_events = None
+        if not turn_events:
+            return
+        from ksadk.memory.coordinator import agent_user_scope_id
+
+        candidates = propose_memory_candidates(
+            list(turn_events),
+            scope="user",
+            scope_id=agent_user_scope_id(
+                agent_id=ctx.agent_id,
+                user_id=ctx.user_id,
+            ),
+        )
+        # explicit_only：只保留用户明确要求记住的内容（方案 §2）
+        if policy.is_explicit_only:
+            candidates = [c for c in candidates if c.reason.startswith("explicit_user_")]
+        provider_name = ctx.provider_ref or "local-default"
+        rollout = policy.write_rollout
+        if candidates:
+            # shadow：生成候选和审计事件，但不提交 Provider（方案 §2）
+            if policy.should_flush:
+                provider = resolve_memory_provider(ctx.provider_ref)
+                from ksadk.memory.provider_adapter import adapt_as_memory_provider
+
+                provider = adapt_as_memory_provider(provider)
+                coordinator = MemoryCoordinator(provider)
+                result = coordinator.flush_candidates(candidates)
+            else:
+                # shadow：不提交，构造一个不落库的 result
+                from ksadk.memory.coordinator import FlushResult
+
+                result = FlushResult(
+                    status="shadow",
+                    proposed=len(candidates),
+                    committed=0,
+                    rejected=0,
+                )
+            _emit(
+                ctx,
+                candidate_created(
+                    run_id=ctx.invocation_id,
+                    session_id=ctx.session_id,
+                    provider=provider_name,
+                    rollout=rollout,
+                    count=len(candidates),
+                ),
+            )
+            if result.rejected > 0:
+                _emit(
+                    ctx,
+                    candidate_rejected(
+                        run_id=ctx.invocation_id,
+                        session_id=ctx.session_id,
+                        provider=provider_name,
+                        rollout=rollout,
+                        count=result.rejected,
+                    ),
+                )
+            # 检查 flush 结果：partial/failed 时发 flush.failed（方案 §3）
+            if result.status in ("succeeded", "shadow"):
+                _emit(
+                    ctx,
+                    flush_completed(
+                        run_id=ctx.invocation_id,
+                        session_id=ctx.session_id,
+                        provider=provider_name,
+                        rollout=rollout,
+                        proposed=result.proposed,
+                        committed=result.committed,
+                        rejected=result.rejected,
+                    ),
+                )
+            else:
+                # partial / failed → flush.failed
+                _emit(
+                    ctx,
+                    flush_failed(
+                        run_id=ctx.invocation_id,
+                        session_id=ctx.session_id,
+                        provider=provider_name,
+                        rollout=rollout,
+                        error_code=f"flush_{result.status}",
+                        error_message=f"{result.status}: {len(result.errors)} errors",
+                        retryable=True,
+                    ),
+                )
+    except Exception as exc:  # noqa: BLE001
+        _emit(
+            ctx,
+            flush_failed(
+                run_id=ctx.invocation_id,
+                session_id=ctx.session_id,
+                provider="sqlite",
+                rollout=ctx.memory_write_rollout or "enabled",
+                error_code="flush_exception",
+                error_message=str(exc)[:200],
+                retryable=True,
+            ),
+        )
+
+
+def _maybe_detect_capability_mismatch(ctx: FinalizeContext) -> None:
+    """证据驱动的 capability mismatch 熔断（方案 §6.1）。"""
+    from ksadk.context_engine.capabilities import (
+        capabilities_for_runtime_type,
+        detect_capability_mismatch,
+        is_capability_circuit_open,
+        mark_capability_mismatch,
+    )
+
+    shadow = ctx.shadow_context_plan or {}
+    runtime_type = str(shadow.get("runtime_type") or "")
+    if not runtime_type:
+        return
+    if is_capability_circuit_open(runtime_type=runtime_type):
+        return
+    caps = capabilities_for_runtime_type(runtime_type)
+    has_usage = isinstance(ctx.usage, Mapping) and bool(ctx.usage)
+    reason = detect_capability_mismatch(
+        declared=caps,
+        runtime_reported_usage=has_usage if has_usage else False,
+    )
+    if reason and "runtime_reported" in reason:
+        mark_capability_mismatch(runtime_type=runtime_type)
+
+
+__all__ = ["FinalizeContext", "finalize_hosted_turn"]
+
+
+# 内存事件收集器（best-effort，不阻断主链路）
+def _emit(ctx: Any, event: Any) -> None:
+    """发送 Memory 事件到 ctx.emit_event（方案 §3）。"""
+    sink = getattr(ctx, "emit_event", None)
+    if callable(sink):
+        try:
+            sink(event.to_dict())
+        except Exception:  # noqa: BLE001
+            pass