capability-runtime 0.1.0__tar.gz → 0.1.1__tar.gz

{capability_runtime-0.1.0 → capability_runtime-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capability-runtime
-Version: 0.1.0
+Version: 0.1.1
 Summary: Bridge/glue layer that composes Agently (LLM/TriggerFlow) with skills-runtime-sdk (skills/tools/WAL/events).
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -8,7 +8,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: PyYAML>=6
 Requires-Dist: pydantic<3,>=2
 Requires-Dist: agently==4.0.8
-Requires-Dist: skills-runtime-sdk==0.1.11
+Requires-Dist: skills-runtime-sdk==0.1.12
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

{capability_runtime-0.1.0 → capability_runtime-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "capability-runtime"
-version = "0.1.0"
+version = "0.1.1"
 description = "Bridge/glue layer that composes Agently (LLM/TriggerFlow) with skills-runtime-sdk (skills/tools/WAL/events)."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -9,7 +9,7 @@ dependencies = [
   "PyYAML>=6",
   "pydantic>=2,<3",
   "agently==4.0.8",
-  "skills-runtime-sdk==0.1.11",
+  "skills-runtime-sdk==0.1.12",
 ]
 
 [project.optional-dependencies]

{capability_runtime-0.1.0 → capability_runtime-0.1.1}/src/capability_runtime/__init__.py

@@ -1,7 +1,7 @@
 """capability-runtime：统一 Runtime 入口（能力协议 + 执行 + 报告）。"""
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 # === 统一入口 ===
 from .config import CustomTool, RuntimeConfig
@@ -18,7 +18,7 @@ from .host_protocol import ApprovalTicket, HostRunSnapshot, HostRunStatus, Resum
 from .manifest import CapabilityDescriptor, CapabilityManifestEntry, CapabilityVisibility
 
 # === Protocol 导出 ===
-from .protocol.agent import AgentIOSchema, AgentSpec
+from .protocol.agent import AgentIOSchema, AgentSpec, PromptRenderMode
 from .protocol.capability import (
     CapabilityKind,
     CapabilityRef,
@@ -76,6 +76,7 @@ __all__ = [
     "RuntimeServiceFacade",
     "AgentSpec",
     "AgentIOSchema",
+    "PromptRenderMode",
     "WorkflowSpec",
     "Step",
     "LoopStep",

{capability_runtime-0.1.0 → capability_runtime-0.1.1}/src/capability_runtime/adapters/agent_adapter.py

@@ -10,8 +10,11 @@ AgentAdapter：AgentSpec 的执行适配器（统一 mock/bridge/sdk_native）
 from __future__ import annotations
 
 import asyncio
+import hashlib
 import inspect
 import json
+import re
+from dataclasses import dataclass
 from typing import Any, AsyncIterator, Dict, List, Optional, Union
 
 from skills_runtime.core.contracts import AgentEvent
@@ -30,6 +33,34 @@ _SECTION_TASK = "## 任务"
 _SECTION_INPUT = "## 输入"
 _SECTION_OUTPUT_PREFIX = "## 输出要求"
 _SECTION_SKILLS = "## 使用以下 Skills"
+_RUNTIME_PROMPT_KEY = "_runtime_prompt"
+_PROMPT_HASH_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+_ALLOWED_PROMPT_ROLES = {"system", "developer", "user", "assistant", "tool"}
+_ALLOWED_PROMPT_PROFILES = {"default_agent", "generation_direct", "structured_transform"}
+
+
+class _InvalidPromptMessages(ValueError):
+    """prompt control envelope 非法。"""
+
+
+@dataclass(frozen=True)
+class _PromptRenderPlan:
+    """
+    AgentAdapter 内部 prompt 渲染计划。
+
+    字段：
+    - mode：三种 prompt rendering strategy 之一；
+    - task：传给 SDK Agent.run_stream_async 的 task 文本；
+    - prompt_profile：透传给上游 SDK 的 prompt profile；
+    - precomposed_messages：最终 provider messages 覆写；
+    - evidence：写入 NodeReport.meta 的最小披露摘要。
+    """
+
+    mode: str
+    task: str
+    prompt_profile: Optional[str]
+    precomposed_messages: Optional[List[Dict[str, Any]]]
+    evidence: Dict[str, Any]
 
 
 class AgentAdapter:
@@ -168,6 +199,29 @@ class AgentAdapter:
         真实执行（bridge/sdk_native）：驱动 SDK Agent.run_stream_async 并聚合 NodeReport。
         """
 
+        try:
+            prompt_plan = self._resolve_prompt_render_plan(spec=spec, input=input)
+        except _InvalidPromptMessages as exc:
+            report = self._services.build_fail_closed_report(
+                run_id=context.run_id,
+                status="failed",
+                reason="invalid_prompt_messages",
+                completion_reason="invalid_prompt_messages",
+                meta={
+                    "capability_id": spec.base.id,
+                    "source": "prompt_rendering",
+                    "prompt_error": str(exc),
+                },
+            )
+            yield CapabilityResult(
+                status=CapabilityStatus.FAILED,
+                error=str(exc),
+                error_code="INVALID_PROMPT_MESSAGES",
+                report=report,
+                node_report=report,
+            )
+            return
+
         # preflight gate（生产默认 fail-closed）
         issues: List[FrameworkIssue] = []
         if getattr(self._services.config, "preflight_mode", "error") != "off":
@@ -184,6 +238,7 @@ class AgentAdapter:
                         "code": "SKILL_PREFLIGHT_FAILED",
                         "details": {"issues": [self._services.redact_issue(i) for i in issues]},
                     },
+                    **prompt_plan.evidence,
                 },
             )
             yield CapabilityResult(
@@ -196,8 +251,34 @@ class AgentAdapter:
             )
             return
 
-        task = self._build_task(spec=spec, input=input)
-        agent = self._services.create_sdk_agent(llm_config=spec.llm_config)
+        task = prompt_plan.task
+        create_agent_kwargs: Dict[str, Any] = {"llm_config": spec.llm_config}
+        if prompt_plan.prompt_profile is not None:
+            create_agent_kwargs["prompt_profile"] = prompt_plan.prompt_profile
+        if prompt_plan.precomposed_messages is not None:
+            create_agent_kwargs["precomposed_messages"] = prompt_plan.precomposed_messages
+        try:
+            agent = self._services.create_sdk_agent(**create_agent_kwargs)
+        except Exception as exc:
+            report = self._services.build_fail_closed_report(
+                run_id=context.run_id,
+                status="failed",
+                reason="engine_error",
+                completion_reason="engine_exception",
+                meta={
+                    "source": "sdk_agent_create",
+                    "engine_exception": type(exc).__name__,
+                    **prompt_plan.evidence,
+                },
+            )
+            yield CapabilityResult(
+                status=CapabilityStatus.FAILED,
+                error=str(exc),
+                error_code="ENGINE_ERROR",
+                report=report,
+                node_report=report,
+            )
+            return
 
         events: List[AgentEvent] = []
         host_meta = self._services.get_host_meta(context=context)
@@ -241,6 +322,7 @@ class AgentAdapter:
                 completion_reason="run_cancelled",
                 meta={"capability_id": spec.base.id, "source": "sdk_agent"},
             )
+            self._apply_prompt_evidence(report=report, evidence=prompt_plan.evidence)
             yield CapabilityResult(
                 status=CapabilityStatus.CANCELLED,
                 error="execution cancelled",
@@ -255,7 +337,7 @@ class AgentAdapter:
                 status="failed",
                 reason="engine_error",
                 completion_reason="engine_exception",
-                meta={"engine_exception": type(exc).__name__},
+                meta={"engine_exception": type(exc).__name__, **prompt_plan.evidence},
             )
             yield CapabilityResult(
                 status=CapabilityStatus.FAILED,
@@ -267,6 +349,7 @@ class AgentAdapter:
             return
 
         report = NodeReportBuilder().build(events=events)
+        self._apply_prompt_evidence(report=report, evidence=prompt_plan.evidence)
         if issues and getattr(self._services.config, "preflight_mode", "error") == "warn":
             report.meta["preflight_mode"] = "warn"
             report.meta["preflight_issues"] = [self._services.redact_issue(i) for i in issues]
@@ -306,6 +389,166 @@ class AgentAdapter:
             artifacts=list(report.artifacts),
         )
 
+    def _resolve_prompt_render_plan(self, *, spec: AgentSpec, input: Dict[str, Any]) -> _PromptRenderPlan:
+        """
+        解析 AgentSpec + run-level `_runtime_prompt`，生成 prompt 渲染计划。
+
+        参数：
+        - spec：Agent 声明
+        - input：run 输入，其中 `_runtime_prompt` 为保留控制面
+
+        返回：
+        - `_PromptRenderPlan`
+
+        异常：
+        - `_InvalidPromptMessages`：控制面非法，调用方应 fail-fast。
+        """
+
+        envelope_raw = input.get(_RUNTIME_PROMPT_KEY)
+        if envelope_raw is None:
+            envelope: Dict[str, Any] = {}
+        elif isinstance(envelope_raw, dict):
+            envelope = dict(envelope_raw)
+        else:
+            raise _InvalidPromptMessages("_runtime_prompt must be a dict")
+
+        raw_mode = envelope.get("mode") if "mode" in envelope else getattr(spec, "prompt_render_mode", "structured_task")
+        if raw_mode is None:
+            raw_mode = "structured_task"
+        if not isinstance(raw_mode, str) or not raw_mode.strip():
+            raise _InvalidPromptMessages("prompt render mode must be a non-empty string")
+        mode = raw_mode.strip()
+        if mode not in {"structured_task", "direct_task_text", "precomposed_messages"}:
+            raise _InvalidPromptMessages(
+                "unsupported prompt render mode; allowed: direct_task_text, precomposed_messages, structured_task"
+            )
+
+        prompt_profile = envelope.get("profile")
+        if prompt_profile is None:
+            prompt_profile = getattr(spec, "prompt_profile", None)
+        if prompt_profile is not None:
+            if not isinstance(prompt_profile, str) or not prompt_profile.strip():
+                raise _InvalidPromptMessages("prompt profile must be a non-empty string")
+            prompt_profile = prompt_profile.strip()
+            if prompt_profile not in _ALLOWED_PROMPT_PROFILES:
+                allowed = ", ".join(sorted(_ALLOWED_PROMPT_PROFILES))
+                raise _InvalidPromptMessages(f"unsupported prompt profile; allowed: {allowed}")
+
+        trace = envelope.get("trace") if "trace" in envelope else {}
+        if trace is None:
+            trace = {}
+        if not isinstance(trace, dict):
+            raise _InvalidPromptMessages("_runtime_prompt.trace must be a dict")
+        prompt_hash = trace.get("prompt_hash")
+        if prompt_hash is not None:
+            if not isinstance(prompt_hash, str) or _PROMPT_HASH_RE.fullmatch(prompt_hash.strip()) is None:
+                raise _InvalidPromptMessages("trace.prompt_hash must match sha256:<64 lowercase hex>")
+            prompt_hash = prompt_hash.strip()
+        composer_version = trace.get("composer_version")
+        if composer_version is not None and not isinstance(composer_version, str):
+            raise _InvalidPromptMessages("trace.composer_version must be a string")
+
+        if mode == "structured_task":
+            business_input = self._strip_runtime_prompt(input)
+            task = self._build_task(spec=spec, input=business_input)
+            evidence = self._build_prompt_evidence(
+                mode=mode,
+                prompt_profile=prompt_profile,
+                prompt_hash=prompt_hash or _hash_text(task),
+                composer_version=composer_version,
+                messages=None,
+            )
+            return _PromptRenderPlan(
+                mode=mode,
+                task=task,
+                prompt_profile=prompt_profile,
+                precomposed_messages=None,
+                evidence=evidence,
+            )
+
+        if mode == "direct_task_text":
+            task_text = envelope.get("task_text")
+            if not isinstance(task_text, str) or not task_text.strip():
+                raise _InvalidPromptMessages("_runtime_prompt.task_text must be a non-empty string")
+            task = task_text
+            evidence = self._build_prompt_evidence(
+                mode=mode,
+                prompt_profile=prompt_profile,
+                prompt_hash=prompt_hash or _hash_text(task),
+                composer_version=composer_version,
+                messages=None,
+            )
+            return _PromptRenderPlan(
+                mode=mode,
+                task=task,
+                prompt_profile=prompt_profile,
+                precomposed_messages=None,
+                evidence=evidence,
+            )
+
+        messages = _validate_precomposed_messages(envelope.get("messages"))
+        evidence = self._build_prompt_evidence(
+            mode=mode,
+            prompt_profile=prompt_profile,
+            prompt_hash=prompt_hash or _hash_messages(messages),
+            composer_version=composer_version,
+            messages=messages,
+        )
+        return _PromptRenderPlan(
+            mode=mode,
+            task="",
+            prompt_profile=prompt_profile,
+            precomposed_messages=messages,
+            evidence=evidence,
+        )
+
+    def _build_prompt_evidence(
+        self,
+        *,
+        mode: str,
+        prompt_profile: Optional[str],
+        prompt_hash: str,
+        composer_version: Any,
+        messages: Optional[List[Dict[str, Any]]],
+    ) -> Dict[str, Any]:
+        """
+        构造 NodeReport.meta 的 prompt 最小披露摘要。
+
+        参数：
+        - mode：prompt render mode
+        - prompt_profile：可选 SDK prompt profile
+        - prompt_hash：`sha256:<hex>` 摘要
+        - composer_version：可选 composer 版本
+        - messages：precomposed messages；仅用于 count/roles 摘要
+        """
+
+        evidence: Dict[str, Any] = {
+            "prompt_render_mode": mode,
+            "prompt_hash": prompt_hash,
+        }
+        if prompt_profile:
+            evidence["prompt_profile"] = prompt_profile
+        if isinstance(composer_version, str) and composer_version:
+            evidence["prompt_composer_version"] = composer_version
+        if messages is not None:
+            evidence["prompt_messages_count"] = len(messages)
+            evidence["prompt_message_roles"] = [str(item["role"]) for item in messages]
+        return evidence
+
+    def _strip_runtime_prompt(self, input: Dict[str, Any]) -> Dict[str, Any]:
+        """从业务 input 中剥离 runtime prompt 控制面。"""
+
+        if _RUNTIME_PROMPT_KEY not in input:
+            return input
+        return {k: v for k, v in input.items() if k != _RUNTIME_PROMPT_KEY}
+
+    def _apply_prompt_evidence(self, *, report: Any, evidence: Dict[str, Any]) -> None:
+        """把 prompt evidence 写入 NodeReport.meta；兼容测试中的 dict fake report。"""
+
+        meta = getattr(report, "meta", None)
+        if isinstance(meta, dict):
+            meta.update(evidence)
+
     def _build_task(self, *, spec: AgentSpec, input: Dict[str, Any]) -> str:
         """
         将 AgentSpec + input 转换为 SDK Agent 的 task 文本（结构化拼接）。
@@ -323,9 +566,10 @@ class AgentAdapter:
         if spec.base.description:
             parts.append(f"{_SECTION_TASK}\n{spec.base.description}")
 
-        if input:
+        business_input = self._strip_runtime_prompt(input)
+        if business_input:
             lines: List[str] = []
-            for k, v in input.items():
+            for k, v in business_input.items():
                 if isinstance(v, str):
                     lines.append(f"- {k}: {v}")
                 else:
@@ -437,3 +681,48 @@ class AgentAdapter:
             if account and domain:
                 return f"[{account}:{domain}]"
         return None
+
+
+def _hash_text(text: str) -> str:
+    """生成 prompt 文本的 sha256 摘要。"""
+
+    return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _hash_messages(messages: List[Dict[str, Any]]) -> str:
+    """对 provider messages 做稳定 JSON canonicalization 后生成摘要。"""
+
+    canonical = json.dumps(messages, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return _hash_text(canonical)
+
+
+def _validate_precomposed_messages(raw: Any) -> List[Dict[str, Any]]:
+    """
+    校验 host 提供的最终 provider messages。
+
+    约束：
+    - 只接受非空 list[dict]；
+    - 每条消息必须有合法 role 与字符串 content；
+    - 返回浅拷贝，避免后续执行链路修改调用方输入。
+    """
+
+    if not isinstance(raw, list):
+        raise _InvalidPromptMessages("_runtime_prompt.messages must be a list")
+    if not raw:
+        raise _InvalidPromptMessages("_runtime_prompt.messages must not be empty")
+
+    out: List[Dict[str, Any]] = []
+    for idx, item in enumerate(raw):
+        if not isinstance(item, dict):
+            raise _InvalidPromptMessages(f"_runtime_prompt.messages[{idx}] must be a dict")
+        role = item.get("role")
+        content = item.get("content")
+        if not isinstance(role, str) or role not in _ALLOWED_PROMPT_ROLES:
+            raise _InvalidPromptMessages(f"_runtime_prompt.messages[{idx}].role is invalid")
+        if not isinstance(content, str):
+            raise _InvalidPromptMessages(f"_runtime_prompt.messages[{idx}].content must be a string")
+        copied = dict(item)
+        copied["role"] = role
+        copied["content"] = content
+        out.append(copied)
+    return out

{capability_runtime-0.1.0 → capability_runtime-0.1.1}/src/capability_runtime/protocol/__init__.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 """Protocol 层：纯能力类型定义，不依赖任何上游模块。"""
 
-from .agent import AgentIOSchema, AgentSpec
+from .agent import AgentIOSchema, AgentSpec, PromptRenderMode
 from .capability import (
     CapabilityKind,
     CapabilityRef,
@@ -30,6 +30,7 @@ __all__ = [
     "CapabilityResult",
     "AgentSpec",
     "AgentIOSchema",
+    "PromptRenderMode",
     "ChatBackendProtocol",
     "WorkflowSpec",
     "Step",

{capability_runtime-0.1.0 → capability_runtime-0.1.1}/src/capability_runtime/protocol/agent.py

@@ -3,11 +3,14 @@ from __future__ import annotations
 """Agent 元能力声明。"""
 
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Literal, Optional
 
 from .capability import CapabilityRef, CapabilitySpec
 
 
+PromptRenderMode = Literal["structured_task", "direct_task_text", "precomposed_messages"]
+
+
 @dataclass(frozen=True)
 class AgentIOSchema:
     """
@@ -36,6 +39,8 @@ class AgentSpec:
     - output_schema: 输出 schema（可选）
     - loop_compatible: 是否可被 LoopStep 循环调用
     - llm_config: LLM 覆盖配置
+    - prompt_render_mode: prompt 渲染模式（默认 structured_task，保持兼容）
+    - prompt_profile: 可选上游 SDK prompt profile（如 generation_direct）
     - prompt_template: 可选的 prompt 模板（支持 {field} 占位符）
     - system_prompt: 可选的“Agent 级 system message”（用于该 Agent 的提示词组织）
 
@@ -58,5 +63,7 @@ class AgentSpec:
     output_schema: Optional[AgentIOSchema] = None
     loop_compatible: bool = False
     llm_config: Optional[Dict[str, Any]] = None
+    prompt_render_mode: PromptRenderMode = "structured_task"
+    prompt_profile: Optional[str] = None
     prompt_template: Optional[str] = None
     system_prompt: Optional[str] = None

{capability_runtime-0.1.0 → capability_runtime-0.1.1}/src/capability_runtime/runtime.py

@@ -914,17 +914,30 @@ class Runtime(RuntimeUIEventsMixin):
             return []
         return self._sdk.preflight()
 
-    def create_sdk_agent(self, *, llm_config: Optional[Dict[str, Any]] = None) -> Any:
+    def create_sdk_agent(
+        self,
+        *,
+        llm_config: Optional[Dict[str, Any]] = None,
+        prompt_profile: Optional[str] = None,
+        precomposed_messages: Optional[List[Dict[str, Any]]] = None,
+    ) -> Any:
         """
         RuntimeServices 协议方法：创建 per-run SDK Agent。
 
         参数：
-        - llm_config：可选 LLM 覆写配置（当前仅支持 `model` 字段覆写）
+        - llm_config：可选 LLM 覆写配置
+        - prompt_profile：可选 SDK prompt profile
+        - precomposed_messages：可选最终 provider messages 覆写
         """
 
         if self._sdk is None:
             raise RuntimeError("SDK lifecycle is not initialized")
-        return self._sdk.create_agent(custom_tools=list(self._config.custom_tools), llm_config=llm_config)
+        return self._sdk.create_agent(
+            custom_tools=list(self._config.custom_tools),
+            llm_config=llm_config,
+            prompt_profile=prompt_profile,
+            precomposed_messages=precomposed_messages,
+        )
 
 
 __all__ = ["Runtime"]

{capability_runtime-0.1.0 → capability_runtime-0.1.1}/src/capability_runtime/sdk_lifecycle.py

@@ -2,9 +2,11 @@ from __future__ import annotations
 
 """SDK 生命周期组件：初始化、预检与 per-run Agent 创建。"""
 
+import hashlib
 import inspect
-from datetime import datetime, timezone
+import uuid
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, AsyncGenerator, AsyncIterator, Dict, List, Optional
 
@@ -83,13 +85,22 @@ class SdkLifecycle:
                 )
             ]
 
-    def create_agent(self, *, custom_tools: List[CustomTool], llm_config: Optional[Dict[str, Any]] = None) -> Any:
+    def create_agent(
+        self,
+        *,
+        custom_tools: List[CustomTool],
+        llm_config: Optional[Dict[str, Any]] = None,
+        prompt_profile: Optional[str] = None,
+        precomposed_messages: Optional[List[Dict[str, Any]]] = None,
+    ) -> Any:
         """
         创建 per-run SDK Agent 实例（避免跨 run 共享可变状态）。
 
         参数：
         - custom_tools：每次创建 Agent 时要注册的自定义工具列表
         - llm_config：可选 LLM 覆写配置（当前支持 `model`、`tool_choice` 与 `response_format` 字段覆写）
+        - prompt_profile：可选 SDK prompt profile，通过 per-run config overlay 透传给上游
+        - precomposed_messages：可选最终 provider messages 覆写
         """
 
         from skills_runtime.core.agent import Agent
@@ -106,12 +117,23 @@ class SdkLifecycle:
         override_response_format = _extract_response_format_override(llm_config)
         if override_response_format is not None:
             backend = _ResponseFormatOverrideBackend(backend=backend, response_format=override_response_format)
+        if precomposed_messages is not None:
+            backend = _PrecomposedMessagesBackend(backend=backend, messages=precomposed_messages)
         usage_bridge_backend = _UsageTapBackend(backend=backend)
         backend = usage_bridge_backend
 
+        config_paths = list(self._state.config_paths)
+        prompt_profile_overlay: Optional[Path] = None
+        if prompt_profile is not None:
+            prompt_profile_overlay = _write_prompt_profile_overlay(
+                workspace_root=self._state.workspace_root,
+                prompt_profile=prompt_profile,
+            )
+            config_paths.append(prompt_profile_overlay)
+
         kwargs: Dict[str, Any] = {
             "workspace_root": self._state.workspace_root,
-            "config_paths": list(self._state.config_paths),
+            "config_paths": config_paths,
             "env_vars": dict(self._config.env_vars),
             "backend": backend,
             "human_io": self._config.human_io,
@@ -124,7 +146,18 @@ class SdkLifecycle:
             "wal_backend": self._config.wal_backend,
         }
 
-        agent = Agent(**kwargs)
+        try:
+            agent = Agent(**kwargs)
+        finally:
+            if prompt_profile_overlay is not None:
+                try:
+                    prompt_profile_overlay.unlink(missing_ok=True)
+                except Exception as exc:
+                    log_suppressed_exception(
+                        context="prompt_profile_overlay_cleanup",
+                        exc=exc,
+                        extra={"path": str(prompt_profile_overlay)},
+                    )
         diagnostics: Dict[str, Dict[str, bool]] = {}
         for t in custom_tools:
             diagnostics[t.spec.name] = _register_custom_tool_compat(agent, t)
@@ -558,6 +591,39 @@ class _ResponseFormatOverrideBackend:
             yield ev
 
 
+class _PrecomposedMessagesBackend:
+    """
+    ChatBackend 薄代理：仅覆写 request.messages，然后委托给底层 backend。
+
+    说明：
+    - 该包装不绕过 SDK Agent / WAL / events，只在 provider request 出口替换 messages；
+    - messages 做浅拷贝转发，避免下游 backend 修改 host 输入。
+    """
+
+    def __init__(self, *, backend: ChatBackendProtocol, messages: List[Dict[str, Any]]) -> None:
+        self._backend: ChatBackendProtocol = backend
+        self._messages: List[Dict[str, Any]] = [dict(item) for item in messages]
+
+    async def stream_chat(self, request: ChatRequest) -> AsyncGenerator[ChatStreamEvent, None]:
+        """
+        覆写 request.messages 并转发 `stream_chat`。
+
+        参数：
+        - request：上游 SDK 生成的 ChatRequest（或兼容对象）
+        """
+
+        forwarded = _clone_request_with_field_update(
+            request,
+            field_name="messages",
+            value=[dict(item) for item in self._messages],
+            dataclasses_context="precomposed_messages_dataclasses_replace",
+            clone_context="precomposed_messages_override",
+        )
+
+        async for ev in self._backend.stream_chat(forwarded):
+            yield ev
+
+
 class _UsageTapBackend:
     """
     ChatBackend 薄代理：通过 request.extra 注入 usage sink，best-effort 收集 bridge usage。
@@ -737,6 +803,36 @@ def _clone_request_with_extra(request: Any, update_extra: Any) -> Any:
     return forwarded
 
 
+def _write_prompt_profile_overlay(*, workspace_root: Path, prompt_profile: str) -> Path:
+    """
+    写入 per-run prompt profile SDK overlay，并返回 overlay 路径。
+
+    说明：
+    - 只写 profile 名称，不写 prompt 明文；
+    - 文件名使用 profile 摘要，避免 profile 字符串直接进入路径。
+    """
+
+    import yaml
+
+    profile = str(prompt_profile).strip()
+    if not profile:
+        raise ValueError("prompt_profile must be a non-empty string")
+
+    digest = hashlib.sha256(profile.encode("utf-8")).hexdigest()[:16]
+    overlay_dir = Path(workspace_root) / ".skills_runtime_sdk"
+    overlay_dir.mkdir(parents=True, exist_ok=True)
+    overlay_path = overlay_dir / f"caprt_prompt_profile_{digest}_{uuid.uuid4().hex}.yaml"
+    overlay_path.write_text(
+        yaml.safe_dump(
+            {"prompt": {"profile": profile}},
+            allow_unicode=True,
+            sort_keys=True,
+        ),
+        encoding="utf-8",
+    )
+    return overlay_path
+
+
 def _load_yaml_dict(path: Path) -> Dict[str, Any]:
     """
     读取 YAML 文件并返回 dict。