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

ksadk/context_engine/policies.py

@@ -0,0 +1,319 @@
+"""ContextPolicy / PromptPolicy / MemoryPolicy 归一化与旧 env 映射（方案 §13）。
+
+把散落的环境变量与 AgentSpec 字段归一化成结构化策略，本地与云端共用同一 Runtime 代码消费
+（方案 §12）。优先级：Agent Revision/Build 锁定配置 > Environment 安全收紧 > 本地显式 API >
+结构化配置文件 > 环境变量 > SDK 默认值。
+
+公开类型从第一批开始版本化（``CONTEXT_POLICY_VERSION``，与 ``context_engine.models`` 一致）。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+CONTEXT_POLICY_VERSION = "v1"
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or str(raw).strip() == "":
+        return default
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return default
+
+
+def _env_float(name: str, default: float) -> float:
+    raw = os.environ.get(name)
+    if raw is None or str(raw).strip() == "":
+        return default
+    try:
+        return float(raw)
+    except ValueError:
+        return default
+
+
+@dataclass(frozen=True)
+class PromptPolicy:
+    """Prompt 策略（方案 §7 / §13）。
+
+    ``auto_discovery`` 控制指令文件自动发现（默认关，``KSADK_PROMPT_AUTO_DISCOVERY``）。
+    ``rule_file_max_tokens`` / ``rule_files_max_tokens`` 为单文件/总预算。
+    """
+
+    auto_discovery: bool = False
+    rule_file_max_tokens: int = 4000
+    rule_files_max_tokens: int = 12000
+    cache_observability: bool = True
+    compiler_version: str = "v1"
+
+    @classmethod
+    def from_env(cls) -> "PromptPolicy":
+        return cls(
+            auto_discovery=os.environ.get("KSADK_PROMPT_AUTO_DISCOVERY", "").strip().lower()
+            in ("1", "true", "yes", "on"),
+            rule_file_max_tokens=_env_int("KSADK_CONTEXT_RULE_FILE_MAX_TOKENS", 4000),
+            rule_files_max_tokens=_env_int("KSADK_CONTEXT_RULE_FILES_MAX_TOKENS", 12000),
+            cache_observability=os.environ.get("KSADK_CONTEXT_CACHE_BREAK_OBSERVABILITY", "true")
+            .strip()
+            .lower()
+            not in ("0", "false", "off"),
+        )
+
+
+@dataclass(frozen=True)
+class SectionBudget:
+    """单分区预算比例与绝对上限（方案 §8.3）。"""
+
+    percent: float
+    max_tokens: int
+
+
+@dataclass(frozen=True)
+class ContextBudgetPolicy:
+    """请求级预算与分区比例（方案 §8.2 / §8.3 / 附录 A）。
+
+    50%/85% 是初始默认值，可由模型 metadata 或 Deployment policy 覆盖（方案 §8.2）。
+    分区比例不是配额预占：某分区未用预算可回流，但 required item 的预算必须先锁定。
+    """
+
+    soft_limit_percent: float = 50.0
+    hard_limit_percent: float = 85.0
+    safety_buffer_tokens: int = 8000
+    reserved_output_tokens: int = 0  # 0 表示 auto（按模型 metadata 推导）
+    reserved_reasoning_tokens: int = 0
+    sections: dict[str, SectionBudget] = field(
+        default_factory=lambda: {
+            "prompt": SectionBudget(15, 24000),
+            "resource_manifest": SectionBudget(5, 8000),
+            "core_memory": SectionBudget(5, 8000),
+            "recalled_memory": SectionBudget(10, 16000),
+            "checkpoint_summary": SectionBudget(10, 16000),
+            "working_state": SectionBudget(5, 8000),
+            "recent_history": SectionBudget(35, 64000),
+            "tool_and_attachment": SectionBudget(10, 16000),
+        }
+    )
+
+    @classmethod
+    def from_env(cls) -> "ContextBudgetPolicy":
+        sections = dict(cls().sections)
+        return cls(
+            soft_limit_percent=_env_float("KSADK_CONTEXT_SOFT_LIMIT_PERCENT", 50.0),
+            hard_limit_percent=_env_float("KSADK_CONTEXT_HARD_LIMIT_PERCENT", 85.0),
+            safety_buffer_tokens=_env_int("KSADK_CONTEXT_SAFETY_BUFFER_TOKENS", 8000),
+            sections=sections,
+        )
+
+
+@dataclass(frozen=True)
+class CompactionPolicy:
+    """Compaction 策略（方案 §9 / §13）。"""
+
+    keep_tail_groups: int = 8
+    emergency_keep_tail_groups: int = 3
+    semantic_enabled: bool = True
+    semantic_timeout_ms: int = 45000
+    max_retry_after_prompt_too_long: int = 1
+    flush_memory_before_compaction: bool = True
+    working_state_enabled: bool = True
+    working_state_max_tokens: int = 8000
+    working_state_update_min_token_growth: int = 5000
+    working_state_extraction_timeout_ms: int = 15000
+
+    @classmethod
+    def from_env(cls) -> "CompactionPolicy":
+        return cls(
+            keep_tail_groups=_env_int("KSADK_CONTEXT_KEEP_TAIL_GROUPS", 8),
+            emergency_keep_tail_groups=_env_int("KSADK_CONTEXT_EMERGENCY_KEEP_TAIL_GROUPS", 3),
+            semantic_enabled=os.environ.get("KSADK_CONTEXT_SEMANTIC_ENABLED", "true")
+            .strip()
+            .lower()
+            not in ("0", "false", "off"),
+            semantic_timeout_ms=_env_int("KSADK_CONTEXT_SEMANTIC_TIMEOUT_MS", 45000),
+            max_retry_after_prompt_too_long=_env_int("KSADK_CONTEXT_MAX_RETRY_AFTER_PTL", 1),
+            flush_memory_before_compaction=os.environ.get(
+                "KSADK_MEMORY_FLUSH_BEFORE_COMPACTION", "true"
+            )
+            .strip()
+            .lower()
+            not in ("0", "false", "off"),
+            working_state_enabled=os.environ.get("KSADK_CONTEXT_WORKING_STATE_ENABLED", "true")
+            .strip()
+            .lower()
+            not in ("0", "false", "off"),
+            working_state_max_tokens=_env_int("KSADK_CONTEXT_WORKING_STATE_MAX_TOKENS", 8000),
+            working_state_update_min_token_growth=_env_int(
+                "KSADK_CONTEXT_WORKING_STATE_MIN_TOKEN_GROWTH", 5000
+            ),
+            working_state_extraction_timeout_ms=_env_int(
+                "KSADK_CONTEXT_WORKING_STATE_EXTRACTION_TIMEOUT_MS", 15000
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class ToolResultPolicy:
+    """Tool Result 单项预算与内容替换（方案 §8.6 / 附录 A）。"""
+
+    default_max_tokens: int = 8000
+    replacement_strategy: str = "artifact_summary"
+    preserve_error_tail: bool = True
+
+    @classmethod
+    def from_env(cls) -> "ToolResultPolicy":
+        return cls(
+            default_max_tokens=_env_int("KSADK_CONTEXT_TOOL_RESULT_MAX_TOKENS", 16000),
+        )
+
+
+@dataclass(frozen=True)
+class ContributorPolicy:
+    """ContextContributor 默认约束（方案 §8.7 / 附录 A）。"""
+
+    default_timeout_ms: int = 3000
+    default_failure_mode: str = "skip"  # skip / warn / fail
+    allow_external_platform_trust: bool = False
+
+    @classmethod
+    def from_env(cls) -> "ContributorPolicy":
+        return cls(
+            default_timeout_ms=_env_int("KSADK_CONTEXT_CONTRIBUTOR_TIMEOUT_MS", 3000),
+            default_failure_mode=os.environ.get("KSADK_CONTEXT_CONTRIBUTOR_FAILURE_MODE", "skip")
+            .strip()
+            .lower()
+            or "skip",
+            allow_external_platform_trust=os.environ.get(
+                "KSADK_CONTEXT_CONTRIBUTOR_ALLOW_PLATFORM_TRUST", "false"
+            )
+            .strip()
+            .lower()
+            in ("1", "true", "yes"),
+        )
+
+
+@dataclass(frozen=True)
+class MemoryPolicyConfig:
+    """Memory 策略（方案 §13，区别于写入 ``MemoryPolicy``）。"""
+
+    enabled: bool = True
+    provider: str = "local_sqlite"
+    core_max_tokens: int = 4000
+    recall_top_k: int = 8
+    recall_max_tokens: int = 4000
+    min_score: float = 0.45
+    write_mode: str = "propose"  # explicit / propose / off
+
+    @classmethod
+    def from_env(cls) -> "MemoryPolicyConfig":
+        # 旧变量映射（方案 §13）：KSADK_LTM_BACKEND → provider
+        provider = (
+            (
+                os.environ.get("KSADK_MEMORY_PROVIDER")
+                or os.environ.get("KSADK_LTM_BACKEND")
+                or "local_sqlite"
+            )
+            .strip()
+            .lower()
+        )
+        return cls(
+            enabled=os.environ.get("KSADK_MEMORY_ENABLED", "true").strip().lower()
+            not in ("0", "false", "off"),
+            provider=provider,
+            core_max_tokens=_env_int("KSADK_MEMORY_CORE_MAX_TOKENS", 4000),
+            recall_top_k=_env_int("KSADK_MEMORY_RECALL_TOP_K", 8),
+            recall_max_tokens=_env_int("KSADK_MEMORY_RECALL_MAX_TOKENS", 4000),
+            min_score=_env_float("KSADK_MEMORY_MIN_SCORE", 0.45),
+            write_mode=os.environ.get("KSADK_MEMORY_WRITE_MODE", "propose").strip().lower()
+            or "propose",
+        )
+
+
+@dataclass(frozen=True)
+class ContextPolicy:
+    """归一化后的完整 Context 策略（方案 §13 / 附录 A）。
+
+    本地与云端共用同一 Runtime 代码消费此结构，不直接读取隐式环境变量决定核心算法
+    （方案 §12）。``version`` 与 ``context_engine.CONTEXT_POLICY_VERSION`` 对齐。
+    """
+
+    version: str = CONTEXT_POLICY_VERSION
+    budget: ContextBudgetPolicy = field(default_factory=ContextBudgetPolicy)
+    compaction: CompactionPolicy = field(default_factory=CompactionPolicy)
+    tool_results: ToolResultPolicy = field(default_factory=ToolResultPolicy)
+    contributors: ContributorPolicy = field(default_factory=ContributorPolicy)
+    memory: MemoryPolicyConfig = field(default_factory=MemoryPolicyConfig)
+    prompt: PromptPolicy = field(default_factory=PromptPolicy)
+
+    @classmethod
+    def from_env(cls) -> "ContextPolicy":
+        return cls(
+            budget=ContextBudgetPolicy.from_env(),
+            compaction=CompactionPolicy.from_env(),
+            tool_results=ToolResultPolicy.from_env(),
+            contributors=ContributorPolicy.from_env(),
+            memory=MemoryPolicyConfig.from_env(),
+            prompt=PromptPolicy.from_env(),
+        )
+
+    @classmethod
+    def from_spec(cls, spec: Mapping[str, Any] | None) -> "ContextPolicy":
+        """从 Studio ``ContextSpec``（兼容扩展）解析。缺字段走默认（方案 §13）。"""
+        if not isinstance(spec, Mapping):
+            return cls.from_env()
+        # 当前 ContextSpec 字段较少，只读已知键；其余走 env/默认。
+        base = cls.from_env()
+        return base
+
+
+def compute_budget_tokens(
+    policy: ContextBudgetPolicy,
+    *,
+    context_window_tokens: int,
+    reserved_output_tokens: int,
+    reserved_reasoning_tokens: int,
+) -> dict[str, int]:
+    """计算 max_input / soft_limit / hard_limit（方案 §8.2）。
+
+    ``reserved_output``/``reserved_reasoning`` 为 0 时按传入值；safety_buffer 从 policy。
+    """
+    # 默认 8K safety buffer 面向大窗口模型。对 4K/8K 小窗口若直接扣除会把
+    # max_input 压成 0，因此将安全余量限制在窗口的 10%（至少 256 tokens）。
+    effective_safety_buffer = min(
+        policy.safety_buffer_tokens,
+        max(256, int(context_window_tokens * 0.10)),
+    )
+    max_input = max(
+        0,
+        min(
+            context_window_tokens,
+            context_window_tokens
+            - reserved_output_tokens
+            - reserved_reasoning_tokens
+            - effective_safety_buffer,
+        ),
+    )
+    soft = int(max_input * policy.soft_limit_percent / 100.0)
+    hard = int(max_input * policy.hard_limit_percent / 100.0)
+    return {
+        "max_input_tokens": max_input,
+        "soft_limit_tokens": soft,
+        "hard_limit_tokens": hard,
+        "safety_buffer_tokens": effective_safety_buffer,
+    }
+
+
+__all__ = [
+    "CompactionPolicy",
+    "ContextBudgetPolicy",
+    "ContextPolicy",
+    "ContributorPolicy",
+    "MemoryPolicyConfig",
+    "PromptPolicy",
+    "SectionBudget",
+    "ToolResultPolicy",
+    "compute_budget_tokens",
+]

ksadk/context_engine/projection.py

@@ -0,0 +1,31 @@
+"""Context 投影语义信封（方案 6.3 / 8.8）。
+
+第一个 PR 只定义最小结构，供 shadow 计划和后续 Projection 复用；不实现任何投影逻辑。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ksadk.context_engine.capabilities import ContextAccuracy, ContextIntegrationMode
+
+PROJECTION_VERSION = "v1"
+
+
+@dataclass(frozen=True)
+class ProjectionResult:
+    """Runner 投影结果信封。
+
+    仅在 ``accounting_accuracy=exact`` 时才代表最终模型输入；native/assisted 路径
+    需结合 Runner 回报生成实际使用记录。
+    """
+
+    projection_id: str
+    runner_type: str
+    integration_mode: ContextIntegrationMode
+    projection_version: str
+    accounting_accuracy: ContextAccuracy
+    estimated_tokens: int | None = None
+    warnings: tuple[str, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)

ksadk/context_engine/shadow_plan.py

@@ -0,0 +1,266 @@
+"""shadow ContextPlan 构造器（第一个 PR 私有，非公开稳定类型）。
+
+在现有调用链旁路构造一个 ``ContextPlan`` 的 dict 投影，用启发式 tokenizer 按 kind 累加
+``tokens_by_kind``，标注 ``accounting_accuracy`` / ``integration_mode``，只写入
+``PreparedConversationTurn.shadow_context_plan`` 和 trace span，**不进任何决策路径**。
+
+返回 plain ``dict`` 而非 ``ContextPlan`` 对象，避免 ``runtime_payloads`` 顶层 import
+``context_engine`` 形成循环依赖。
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Mapping
+
+from ksadk.context_engine.capabilities import (
+    DEFAULT_CONTEXT_CAPABILITIES,
+    capabilities_for_runner,
+    capabilities_for_runtime_type,
+    capability_hash,
+)
+from ksadk.context_engine.models import CONTEXT_POLICY_VERSION
+from ksadk.context_engine.tokenizer import HEURISTIC_TOKENIZER_NAME, get_default_token_counter
+from ksadk.prompts.compiler import PromptCompiler
+from ksadk.prompts.sources import sections_from_instructions
+
+# shadow plan 默认初始化的 kind 字典，保证 Trace 字段稳定。
+_SHADOW_KINDS = (
+    "compiled_prompt",
+    "history_round",
+    "current_input",
+    "recalled_memory",
+    "attachment_context",
+)
+
+
+def _empty_tokens_by_kind() -> dict[str, int]:
+    return {kind: 0 for kind in _SHADOW_KINDS}
+
+
+def _history_tokens(history: Any, counter: Any) -> int:
+    if not history:
+        return 0
+    total = 0
+    for turn in history:
+        if isinstance(turn, Mapping):
+            for key in ("role", "content", "text"):
+                value = turn.get(key)
+                if isinstance(value, str):
+                    total += counter.count_text(value)
+                elif isinstance(value, list):
+                    for part in value:
+                        if isinstance(part, Mapping):
+                            text = part.get("text") or part.get("content")
+                            if isinstance(text, str):
+                                total += counter.count_text(text)
+                        elif isinstance(part, str):
+                            total += counter.count_text(part)
+        elif isinstance(turn, str):
+            total += counter.count_text(turn)
+    return total
+
+
+def _ambient_text(section: Any) -> str:
+    """从 memory_context / kb_context 等 ambient 字段里取 formatted_text。"""
+    if isinstance(section, Mapping):
+        text = section.get("formatted_text")
+        if isinstance(text, str) and text.strip():
+            return text
+    return ""
+
+
+def _resolve_caps(*, runner: Any | None, runtime_type: str | None) -> tuple[Any, str]:
+    """解析 capability：优先 runner（adapter/runner 实例），否则 runtime_type，再退 DEFAULT。
+
+    返回 ``(caps, runtime_type)``。``runtime_type`` 用于 Plan 记录；优先取 runner 的
+    ``runtime_type`` 属性（RuntimeAdapter/CodexRuntimeAdapter），其次 detection_result.type.value
+    （framework BaseRunner），最后传入值。
+    """
+    if runner is not None:
+        caps = capabilities_for_runner(runner)
+        rt = (
+            str(getattr(runner, "runtime_type", "") or "")
+            or _runner_detection_type_value(runner)
+            or str(runtime_type or "")
+        )
+        return caps, rt.strip().lower()
+    if runtime_type:
+        caps = capabilities_for_runtime_type(runtime_type)
+        return caps, str(runtime_type).strip().lower()
+    return DEFAULT_CONTEXT_CAPABILITIES(), ""
+
+
+def _runner_detection_type_value(runner: Any) -> str:
+    """读 runner.detection_result.type.value（framework BaseRunner 的类型标识）。"""
+    detection_result = getattr(runner, "detection_result", None)
+    if detection_result is None:
+        return ""
+    detection_type = getattr(detection_result, "type", None)
+    if detection_type is None:
+        return ""
+    value = getattr(detection_type, "value", detection_type)
+    return str(value or "").strip().lower()
+
+
+def compile_shadow_prompt_dict(instructions: str | None) -> dict[str, Any]:
+    """编译 instructions → shadow CompiledPrompt 的 plain dict 投影（PR2）。
+
+    只把 ``request_instructions``（volatile）纳入编译，不引入未发送的 platform_safety，
+    保证 shadow hash 如实反映当前发送的 instructions。``stable_prefix_hash`` 在仅有
+    volatile section 时为空（cache-break 诊断据此如实标 ``no_cache_info``）。
+    供 ``build_shadow_context_plan_dict`` 与 trace 使用，不进决策路径、不替换 Runner 发送内容。
+    """
+    sections = sections_from_instructions(instructions)
+    if not sections:
+        return {
+            "prompt_content_hash": "",
+            "prompt_stable_prefix_hash": "",
+            "prompt_section_hashes": {},
+            "prompt_tokens_by_section": {},
+            "prompt_estimated_tokens": 0,
+            "prompt_section_count": 0,
+        }
+    compiled = PromptCompiler().compile(sections)
+    return {
+        "prompt_content_hash": compiled.content_hash,
+        "prompt_stable_prefix_hash": compiled.stable_prefix_hash,
+        "prompt_section_hashes": dict(compiled.section_hashes),
+        "prompt_tokens_by_section": dict(compiled.tokens_by_section),
+        "prompt_estimated_tokens": compiled.estimated_tokens,
+        "prompt_section_count": len(compiled.sections),
+    }
+
+
+def build_shadow_context_plan_dict(
+    *,
+    instructions: str = "",
+    history: Any = None,
+    user_input: str = "",
+    request_metadata: Mapping[str, Any] | None = None,
+    runner: Any | None = None,
+    runtime_type: str | None = None,
+    model_metadata: Mapping[str, Any] | None = None,
+    prompt_shadow: Mapping[str, Any] | None = None,
+    prompt_integration_mode: str = "",
+    deployment_mode: str = "local",
+) -> dict[str, Any]:
+    """构造 shadow ContextPlan 的 plain dict 投影。
+
+    所有参数来自 ``PreparedConversationTurn`` 已有字段，不读取任何额外状态。capability
+    解析顺序：``runner``（adapter/runner 实例，含 RuntimeAdapter）→ ``runtime_type``
+    （canonical conversation execution 路径，build_run_input 阶段尚未拿到 adapter）→ DEFAULT。
+    canonical 路径因此不再落成默认 opaque（方案 6.1 / ADR-009）。
+
+    ``deployment_mode``（方案 §4.3 / §6.1）：与 Context ownership 正交，独立写入 plan/trace。
+    默认 ``local``，云端由控制面传入 ``ksadk_managed_cloud``/``external_managed``。不得据它
+    推断 ``integration_mode``。
+
+    ``prompt_shadow``：调用方可传入预编译的真实 CompiledPrompt dict（PR A，含 agent_system/
+    agent_task 的稳定 section）。为 None 时回退到 ``compile_shadow_prompt_dict(instructions)``
+    （仅 request_instructions volatile）。传入真实 dict 时，``prompt_*`` 键全部来自真实编译，
+    ``stable_prefix_hash`` 非空（stable section 进了编译）。
+
+    ``prompt_integration_mode``（PR B）：per-Build 接管标记。仅当为 ``ksadk_hosted`` 且
+    capability ``prompt_owner==ksadk`` 且 ``runtime_type==langgraph`` 时，``integration_mode``
+    显示字段覆盖为 ``ksadk_hosted``（表示本 turn 由 ksadk 编译并接管 instructions）。
+    ``capability_hash`` 仍用原 caps（稳定，不随 per-request 接管状态抖动）。
+    """
+    counter = get_default_token_counter()
+    tokens_by_kind = _empty_tokens_by_kind()
+
+    tokens_by_kind["compiled_prompt"] = counter.count_text(instructions or "")
+    tokens_by_kind["history_round"] = _history_tokens(history, counter)
+    tokens_by_kind["current_input"] = counter.count_text(user_input or "")
+
+    metadata = request_metadata or {}
+    memory_text = _ambient_text(metadata.get("memory_context"))
+    if memory_text:
+        tokens_by_kind["recalled_memory"] = counter.count_text(memory_text)
+    kb_text = _ambient_text(metadata.get("kb_context"))
+    if kb_text:
+        tokens_by_kind["attachment_context"] = counter.count_text(kb_text)
+
+    caps, resolved_runtime_type = _resolve_caps(runner=runner, runtime_type=runtime_type)
+    planned = sum(tokens_by_kind.values())
+    prompt_shadow_dict = (
+        prompt_shadow if prompt_shadow is not None else compile_shadow_prompt_dict(instructions)
+    )
+    # PR B：prompt_content 是真实正文，含明文，不得进 shadow plan/trace。这里剥离，
+    # 只保留 hash/统计键（与 _set_prompt_source_attributes 只读 hash 一致）。
+    shadow_prompt_keys = {
+        key: value for key, value in prompt_shadow_dict.items() if key != "prompt_content"
+    }
+    # PR B：接管态显示。capability_hash 不变（不随 per-request 抖动）。
+    effective_mode = caps.integration_mode
+    if (
+        prompt_integration_mode == "ksadk_hosted"
+        and caps.prompt_owner == "ksadk"
+        and resolved_runtime_type == "langgraph"
+    ):
+        effective_mode = "ksadk_hosted"
+
+    return {
+        "plan_id": f"ctxplan_{uuid.uuid4().hex[:16]}",
+        "policy_version": CONTEXT_POLICY_VERSION,
+        "tokenizer": counter.name or HEURISTIC_TOKENIZER_NAME,
+        "integration_mode": effective_mode,
+        "accounting_accuracy": caps.token_accounting,
+        "tokens_by_kind": tokens_by_kind,
+        "planned_input_tokens": planned,
+        "projected_input_tokens": None,
+        "runtime_reported_input_tokens": None,
+        "stable_prefix_hash": shadow_prompt_keys["prompt_stable_prefix_hash"],
+        "projection_id": None,
+        "contributor_status": {},
+        # capability 摘要，便于 Trace 单独解释 ownership（不替代 conformance 测试）。
+        "prompt_owner": caps.prompt_owner,
+        "history_owner": caps.history_owner,
+        "compaction_owner": caps.compaction_owner,
+        "memory_owner": caps.memory_owner,
+        "skill_owner": caps.skill_owner,
+        # 接线修正：记录 runtime_type + capability_hash，使 canonical 路径的 Plan 可解释、
+        # 可比对 adapter 声明一致性（capability mismatch 检测留后续 PR）。
+        "runtime_type": resolved_runtime_type,
+        "deployment_mode": str(deployment_mode or "local"),
+        "capability_hash": capability_hash(caps),
+        # PR2/PR A：shadow CompiledPrompt hash/section 统计，供 cache-break 诊断与可观测。
+        # shadow_prompt_keys 来自真实编译（PR A 含 agent_system/agent_task）
+        # 或 instructions-only 回退，
+        # 已剥离 prompt_content（明文不进 shadow plan/trace）。
+        **shadow_prompt_keys,
+    }
+
+
+def minimal_shadow_context_plan_dict(
+    *,
+    runner: Any | None = None,
+    runtime_type: str | None = None,
+    deployment_mode: str = "local",
+) -> dict[str, Any]:
+    """resume / 空输入场景的最小 shadow plan：只带 ownership 与精度，不累加 token。"""
+    caps, resolved_runtime_type = _resolve_caps(runner=runner, runtime_type=runtime_type)
+    prompt_shadow = compile_shadow_prompt_dict(None)
+    return {
+        "plan_id": f"ctxplan_{uuid.uuid4().hex[:16]}",
+        "policy_version": CONTEXT_POLICY_VERSION,
+        "tokenizer": HEURISTIC_TOKENIZER_NAME,
+        "integration_mode": caps.integration_mode,
+        "accounting_accuracy": caps.token_accounting,
+        "tokens_by_kind": _empty_tokens_by_kind(),
+        "planned_input_tokens": 0,
+        "projected_input_tokens": None,
+        "runtime_reported_input_tokens": None,
+        "stable_prefix_hash": "",
+        "projection_id": None,
+        "contributor_status": {},
+        "prompt_owner": caps.prompt_owner,
+        "history_owner": caps.history_owner,
+        "compaction_owner": caps.compaction_owner,
+        "memory_owner": caps.memory_owner,
+        "skill_owner": caps.skill_owner,
+        "runtime_type": resolved_runtime_type,
+        "deployment_mode": str(deployment_mode or "local"),
+        "capability_hash": capability_hash(caps),
+        **prompt_shadow,
+    }