capability-runtime 0.1.3.post1__tar.gz → 0.1.5__tar.gz

{capability_runtime-0.1.3.post1 → capability_runtime-0.1.5}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: capability-runtime
-Version: 0.1.3.post1
+Version: 0.1.5
 Summary: Bridge/glue layer that composes Agently (LLM/TriggerFlow) with skills-runtime-sdk (skills/tools/WAL/events).
 License-Expression: MIT
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: PyYAML>=6
 Requires-Dist: pydantic<3,>=2
-Requires-Dist: agently==4.0.8
+Requires-Dist: agently==4.1.3.1
 Requires-Dist: skills-runtime-sdk==0.1.12
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
@@ -40,7 +40,10 @@ The public contract of this repository is intentionally narrow:
 - Public capability registration and manifest descriptors
 - Workflow orchestration on top of the runtime without exposing TriggerFlow as a public API
 - Evidence-first results through `NodeReport`, tool-call reports, approval summaries, and WAL locators
-- Host-facing helpers for wait/resume, approval tickets, continuity, and service streaming
+- Host-facing helpers for waiting summaries, approval tickets, resume-intent preview, continuity, and service streaming
+- Runtime capability previews behind the same runtime contract:
+  Responses requester opt-in, Dynamic DAG preview, workflow lifecycle summaries,
+  Workspace/Recall context packs, and Action artifact evidence summaries
 
 ## Architecture At A Glance
 
@@ -48,7 +51,7 @@ The public contract of this repository is intentionally narrow:
                            +-----------------------------+
                            | Host Application            |
                            | - register capabilities     |
-                           | - run / stream / continue   |
+                           | - run / stream / summarize  |
                            +--------------+--------------+
                                           |
                                           v
@@ -131,7 +134,27 @@ python examples/01_quickstart/run_bridge.py
 ```
 
 Bridge mode reuses Agently's OpenAI-compatible transport but still delegates the
-actual skills/tools/WAL semantics to `skills-runtime-sdk`.
+actual skills/tools/WAL semantics to `skills-runtime-sdk`. The default requester
+strategy is `chat_completions`. Responses mode is an explicit opt-in with
+`RuntimeConfig.requester_strategy="responses"`; it is not the default.
+
+Real provider wiring order:
+
+1. Verify the provider model name with the gateway or `/models` surface.
+2. Build a provider requester factory from neutral transport settings with
+   `build_openai_provider_requester_factory(...)`.
+3. Keep chat/completions on the default `requester_strategy="chat_completions"`.
+4. Opt in to the responses lane only if the provider supports `/responses`.
+5. Run the runtime chat path with
+   `RuntimeConfig(mode="bridge", requester_strategy="chat_completions")`.
+6. Run the runtime responses path with
+   `RuntimeConfig(mode="bridge", requester_strategy="responses")`.
+
+Model routing has a separate priority chain: `AgentSpec.llm_config["model"]`
+overrides the SDK `ChatRequest.model`, and that request model is the runtime
+bridge source of truth when the provider usage payload omits `model`. Agently
+settings configure transport details such as base URL, auth, and requester
+plugin settings; they do not replace `AgentSpec.llm_config.model`.
 
 ### 3. Workflow orchestration
 
@@ -139,6 +162,19 @@ actual skills/tools/WAL semantics to `skills-runtime-sdk`.
 python examples/02_workflow/run.py
 ```
 
+### 4. Runtime capability previews
+
+```bash
+python examples/05_dynamic_dag_preview/run.py
+python examples/06_responses_bridge/run.py
+```
+
+These previews keep the public surface inside `capability_runtime`: use
+`DynamicWorkflowPlan` / runtime methods for Dynamic DAGs and
+`RuntimeConfig.requester_strategy` for Responses. Do not build downstream code on
+upstream-native `TaskDAG`, `DynamicTask`, `Workspace`, `Action`, or requester
+objects.
+
 For a higher-level index, start with [examples/README.md](examples/README.md).
 
 ## Public API At A Glance
@@ -150,6 +186,10 @@ from capability_runtime import (
     Runtime,
     RuntimeConfig,
     CustomTool,
+    ProviderRequester,
+    ProviderRequesterFactory,
+    ProviderRequesterStrategy,
+    build_openai_provider_requester_factory,
     AgentSpec,
     AgentIOSchema,
     WorkflowSpec,
@@ -162,10 +202,19 @@ from capability_runtime import (
     CapabilityKind,
     CapabilityResult,
     CapabilityStatus,
+    DynamicWorkflowNode,
+    DynamicWorkflowPlan,
     NodeReport,
+    StructuredStreamEvent,
     HostRunSnapshot,
+    HostRunStatus,
     ApprovalTicket,
     ResumeIntent,
+    RuntimeContextRecordRef,
+    RuntimeRecallBackend,
+    RuntimeRecallContextPack,
+    build_recall_context_pack,
+    write_node_report_summary,
     RuntimeServiceFacade,
     RuntimeServiceRequest,
     RuntimeServiceHandle,
@@ -176,8 +225,26 @@ from capability_runtime import (
 The runtime currently supports three execution modes through `RuntimeConfig.mode`:
 
 - `mock`: deterministic local testing without a real LLM backend
-- `bridge`: Agently transport + `skills-runtime-sdk` execution semantics
-- `sdk_native`: native `skills-runtime-sdk` backend without Agently transport
+- `bridge`: provider transport adapter + `skills-runtime-sdk` execution semantics
+- `sdk_native`: native `skills-runtime-sdk` backend without the provider transport adapter
+
+Provider bridge strategy is separate from `mode`:
+
+- `RuntimeConfig.requester_strategy="chat_completions"`: backward-compatible
+  default bridge path.
+- `RuntimeConfig.requester_strategy="responses"`: opt-in Responses bridge path.
+- `sdk_backend` injection takes precedence over both strategies for offline
+  regression and fake-backend tests.
+
+Dynamic DAG preview is separate from `WorkflowSpec.steps`: compile a TaskDAG-like
+mapping into the runtime-owned `DynamicWorkflowPlan`, keep `max_dynamic_nodes`
+bounded, and execute nodes only through registered capabilities.
+
+Provider audit evidence is expected in `NodeReport.usage`: preserve
+`model`, `request_id`, `provider`, and token counts when the provider returns
+them. If the provider omits `model`, the request model from `ChatRequest.model`
+is the fallback; never treat an SDK placeholder such as `gpt-4` as real provider
+evidence when a more specific request/provider model is available.
 
 ## Repository Layout
 
@@ -226,7 +293,15 @@ configure the corresponding Trusted Publisher entry on `pypi.org`.
 
 - `skills-runtime-sdk` remains the source of truth for skills, approvals, tools,
   WAL, and event evidence.
+- Agently `SkillsExecutor` is not a `capability-runtime` skills driver. Its
+  authoring patterns may inform `SKILL.md` bundle design, but skill injection,
+  tool execution, approvals, WAL, events, and `NodeReport` aggregation remain
+  owned by `skills-runtime-sdk`.
 - `Agently` remains the transport/orchestration substrate where this repository
   chooses to bridge instead of forking or reimplementing.
 - `capability-runtime` is the contract-convergence layer: it narrows those
   upstream capabilities into a smaller host-facing runtime surface.
+- Default bridge mode is non-breaking: if you do not configure Responses, Dynamic DAG,
+  Workspace/Recall, or Action artifact evidence previews, existing
+  `Runtime.run()` / `Runtime.run_stream()` / `WorkflowSpec` consumers can keep
+  reading the existing `NodeReport` and UI event fields.

{capability_runtime-0.1.3.post1 → capability_runtime-0.1.5}/README.md

@@ -24,7 +24,10 @@ The public contract of this repository is intentionally narrow:
 - Public capability registration and manifest descriptors
 - Workflow orchestration on top of the runtime without exposing TriggerFlow as a public API
 - Evidence-first results through `NodeReport`, tool-call reports, approval summaries, and WAL locators
-- Host-facing helpers for wait/resume, approval tickets, continuity, and service streaming
+- Host-facing helpers for waiting summaries, approval tickets, resume-intent preview, continuity, and service streaming
+- Runtime capability previews behind the same runtime contract:
+  Responses requester opt-in, Dynamic DAG preview, workflow lifecycle summaries,
+  Workspace/Recall context packs, and Action artifact evidence summaries
 
 ## Architecture At A Glance
 
@@ -32,7 +35,7 @@ The public contract of this repository is intentionally narrow:
                            +-----------------------------+
                            | Host Application            |
                            | - register capabilities     |
-                           | - run / stream / continue   |
+                           | - run / stream / summarize  |
                            +--------------+--------------+
                                           |
                                           v
@@ -115,7 +118,27 @@ python examples/01_quickstart/run_bridge.py
 ```
 
 Bridge mode reuses Agently's OpenAI-compatible transport but still delegates the
-actual skills/tools/WAL semantics to `skills-runtime-sdk`.
+actual skills/tools/WAL semantics to `skills-runtime-sdk`. The default requester
+strategy is `chat_completions`. Responses mode is an explicit opt-in with
+`RuntimeConfig.requester_strategy="responses"`; it is not the default.
+
+Real provider wiring order:
+
+1. Verify the provider model name with the gateway or `/models` surface.
+2. Build a provider requester factory from neutral transport settings with
+   `build_openai_provider_requester_factory(...)`.
+3. Keep chat/completions on the default `requester_strategy="chat_completions"`.
+4. Opt in to the responses lane only if the provider supports `/responses`.
+5. Run the runtime chat path with
+   `RuntimeConfig(mode="bridge", requester_strategy="chat_completions")`.
+6. Run the runtime responses path with
+   `RuntimeConfig(mode="bridge", requester_strategy="responses")`.
+
+Model routing has a separate priority chain: `AgentSpec.llm_config["model"]`
+overrides the SDK `ChatRequest.model`, and that request model is the runtime
+bridge source of truth when the provider usage payload omits `model`. Agently
+settings configure transport details such as base URL, auth, and requester
+plugin settings; they do not replace `AgentSpec.llm_config.model`.
 
 ### 3. Workflow orchestration
 
@@ -123,6 +146,19 @@ actual skills/tools/WAL semantics to `skills-runtime-sdk`.
 python examples/02_workflow/run.py
 ```
 
+### 4. Runtime capability previews
+
+```bash
+python examples/05_dynamic_dag_preview/run.py
+python examples/06_responses_bridge/run.py
+```
+
+These previews keep the public surface inside `capability_runtime`: use
+`DynamicWorkflowPlan` / runtime methods for Dynamic DAGs and
+`RuntimeConfig.requester_strategy` for Responses. Do not build downstream code on
+upstream-native `TaskDAG`, `DynamicTask`, `Workspace`, `Action`, or requester
+objects.
+
 For a higher-level index, start with [examples/README.md](examples/README.md).
 
 ## Public API At A Glance
@@ -134,6 +170,10 @@ from capability_runtime import (
     Runtime,
     RuntimeConfig,
     CustomTool,
+    ProviderRequester,
+    ProviderRequesterFactory,
+    ProviderRequesterStrategy,
+    build_openai_provider_requester_factory,
     AgentSpec,
     AgentIOSchema,
     WorkflowSpec,
@@ -146,10 +186,19 @@ from capability_runtime import (
     CapabilityKind,
     CapabilityResult,
     CapabilityStatus,
+    DynamicWorkflowNode,
+    DynamicWorkflowPlan,
     NodeReport,
+    StructuredStreamEvent,
     HostRunSnapshot,
+    HostRunStatus,
     ApprovalTicket,
     ResumeIntent,
+    RuntimeContextRecordRef,
+    RuntimeRecallBackend,
+    RuntimeRecallContextPack,
+    build_recall_context_pack,
+    write_node_report_summary,
     RuntimeServiceFacade,
     RuntimeServiceRequest,
     RuntimeServiceHandle,
@@ -160,8 +209,26 @@ from capability_runtime import (
 The runtime currently supports three execution modes through `RuntimeConfig.mode`:
 
 - `mock`: deterministic local testing without a real LLM backend
-- `bridge`: Agently transport + `skills-runtime-sdk` execution semantics
-- `sdk_native`: native `skills-runtime-sdk` backend without Agently transport
+- `bridge`: provider transport adapter + `skills-runtime-sdk` execution semantics
+- `sdk_native`: native `skills-runtime-sdk` backend without the provider transport adapter
+
+Provider bridge strategy is separate from `mode`:
+
+- `RuntimeConfig.requester_strategy="chat_completions"`: backward-compatible
+  default bridge path.
+- `RuntimeConfig.requester_strategy="responses"`: opt-in Responses bridge path.
+- `sdk_backend` injection takes precedence over both strategies for offline
+  regression and fake-backend tests.
+
+Dynamic DAG preview is separate from `WorkflowSpec.steps`: compile a TaskDAG-like
+mapping into the runtime-owned `DynamicWorkflowPlan`, keep `max_dynamic_nodes`
+bounded, and execute nodes only through registered capabilities.
+
+Provider audit evidence is expected in `NodeReport.usage`: preserve
+`model`, `request_id`, `provider`, and token counts when the provider returns
+them. If the provider omits `model`, the request model from `ChatRequest.model`
+is the fallback; never treat an SDK placeholder such as `gpt-4` as real provider
+evidence when a more specific request/provider model is available.
 
 ## Repository Layout
 
@@ -210,7 +277,15 @@ configure the corresponding Trusted Publisher entry on `pypi.org`.
 
 - `skills-runtime-sdk` remains the source of truth for skills, approvals, tools,
   WAL, and event evidence.
+- Agently `SkillsExecutor` is not a `capability-runtime` skills driver. Its
+  authoring patterns may inform `SKILL.md` bundle design, but skill injection,
+  tool execution, approvals, WAL, events, and `NodeReport` aggregation remain
+  owned by `skills-runtime-sdk`.
 - `Agently` remains the transport/orchestration substrate where this repository
   chooses to bridge instead of forking or reimplementing.
 - `capability-runtime` is the contract-convergence layer: it narrows those
   upstream capabilities into a smaller host-facing runtime surface.
+- Default bridge mode is non-breaking: if you do not configure Responses, Dynamic DAG,
+  Workspace/Recall, or Action artifact evidence previews, existing
+  `Runtime.run()` / `Runtime.run_stream()` / `WorkflowSpec` consumers can keep
+  reading the existing `NodeReport` and UI event fields.

{capability_runtime-0.1.3.post1 → capability_runtime-0.1.5}/pyproject.toml

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

{capability_runtime-0.1.3.post1 → capability_runtime-0.1.5}/src/capability_runtime/__init__.py

@@ -1,13 +1,29 @@
 """capability-runtime：统一 Runtime 入口（能力协议 + 执行 + 报告）。"""
 from __future__ import annotations
 
-__version__ = "0.1.3.post1"
+__version__ = "0.1.5"
 
 # === 统一入口 ===
-from .config import CustomTool, RuntimeConfig
+from .config import (
+    AgentlyRequesterStrategy,
+    CustomTool,
+    ProviderRequester,
+    ProviderRequesterFactory,
+    ProviderRequesterStrategy,
+    RuntimeConfig,
+    ToolChoiceAfterToolResult,
+)
+from .context_pack import (
+    RuntimeContextRecordRef,
+    RuntimeRecallBackend,
+    RuntimeRecallContextPack,
+    build_recall_context_pack,
+    write_node_report_summary,
+)
 from .runtime import Runtime
 from .service_facade import RuntimeServiceFacade, RuntimeServiceHandle, RuntimeServiceRequest, RuntimeSession
 from .structured_stream import StructuredStreamEvent
+from .adapters.agently_backend import build_openai_provider_requester_factory
 
 # === 报告类型 ===
 from .types import NodeReport, NodeResult
@@ -27,6 +43,7 @@ from .protocol.capability import (
     CapabilityStatus,
 )
 from .protocol.context import ExecutionContext
+from .protocol.dynamic_workflow import DynamicWorkflowNode, DynamicWorkflowPlan
 from .protocol.workflow import (
     ConditionalStep,
     InputMapping,
@@ -35,7 +52,6 @@ from .protocol.workflow import (
     Step,
     WorkflowSpec,
 )
-from .services import RuntimeServices
 from .workflow_runtime import WorkflowReplayRequest, WorkflowRunSnapshot, WorkflowRunStatus, WorkflowStepSnapshot
 
 # === 错误导出 ===
@@ -45,8 +61,19 @@ __all__ = [
     # Runtime
     "Runtime",
     "RuntimeConfig",
+    "ProviderRequesterStrategy",
+    "AgentlyRequesterStrategy",
+    "ToolChoiceAfterToolResult",
+    "ProviderRequester",
+    "ProviderRequesterFactory",
     "CustomTool",
     "StructuredStreamEvent",
+    "RuntimeContextRecordRef",
+    "RuntimeRecallBackend",
+    "RuntimeRecallContextPack",
+    "build_recall_context_pack",
+    "write_node_report_summary",
+    "build_openai_provider_requester_factory",
     # Reports
     "NodeReport",
     "NodeResult",
@@ -77,6 +104,8 @@ __all__ = [
     "AgentSpec",
     "AgentIOSchema",
     "PromptRenderMode",
+    "DynamicWorkflowNode",
+    "DynamicWorkflowPlan",
     "WorkflowSpec",
     "Step",
     "LoopStep",
@@ -84,8 +113,11 @@ __all__ = [
     "ConditionalStep",
     "InputMapping",
     "ExecutionContext",
-    "RuntimeServices",
     # Errors
     "RuntimeFrameworkError",
     "CapabilityNotFoundError",
 ]
+
+
+def __getattr__(name: str):
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{capability_runtime-0.1.3.post1 → capability_runtime-0.1.5}/src/capability_runtime/adapters/agent_adapter.py

@@ -20,12 +20,14 @@ from typing import Any, AsyncIterator, Dict, List, Optional, Union
 from skills_runtime.core.contracts import AgentEvent
 from skills_runtime.core.errors import FrameworkIssue
 
+from ..errors import ProviderStreamTerminalError
 from ..logging_utils import log_suppressed_exception
 from ..protocol.agent import AgentSpec
 from ..protocol.capability import CapabilityResult, CapabilityStatus
 from ..protocol.context import ExecutionContext
-from ..reporting.node_report import NodeReportBuilder
+from ..reporting.node_report import NodeReportBuilder, attach_agently_bridge_diagnostics
 from ..services import RuntimeServices, map_node_status
+from ..types import NodeUsageReport
 
 # _build_task 使用的 prompt section 常量
 _SECTION_SYSTEM = "## 系统指令"
@@ -37,6 +39,7 @@ _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"}
+_ALLOWED_IMAGE_DETAILS = {"auto", "low", "high"}
 
 
 class _InvalidPromptMessages(ValueError):
@@ -366,6 +369,67 @@ class AgentAdapter:
                 node_report=report,
             )
             return
+        except ProviderStreamTerminalError as exc:
+            provider_terminal = exc.to_control_payload()
+            if any(ev.type == "provider_stream_terminal" for ev in events):
+                events.append(
+                    AgentEvent(
+                        type="run_failed",
+                        timestamp="",
+                        run_id=context.run_id,
+                        turn_id=None,
+                        payload={"error_kind": exc.reason, "message": exc.message},
+                    )
+                )
+                report = NodeReportBuilder().build(events=events)
+                attach_agently_bridge_diagnostics(
+                    report,
+                    mode=getattr(self._services.config, "mode", ""),
+                    requester_strategy=getattr(self._services.config, "effective_requester_strategy", "chat_completions"),
+                )
+                report.meta["capability_id"] = spec.base.id
+                report.meta["source"] = "provider_stream"
+            else:
+                report = self._services.build_fail_closed_report(
+                    run_id=context.run_id,
+                    status=exc.status,
+                    reason=exc.reason,
+                    completion_reason=exc.completion_reason,
+                    meta={
+                        "capability_id": spec.base.id,
+                        "source": "provider_stream",
+                        "provider_terminal": provider_terminal,
+                        **prompt_plan.evidence,
+                    },
+                )
+                if (
+                    exc.model is not None
+                    or exc.request_id is not None
+                    or exc.provider is not None
+                    or exc.provider_transport is not None
+                ):
+                    report.usage = NodeUsageReport(
+                        model=exc.model,
+                        request_id=exc.request_id,
+                        provider=exc.provider,
+                        provider_transport=exc.provider_transport,
+                    )
+            self._apply_prompt_evidence(report=report, evidence=prompt_plan.evidence)
+            _apply_on_event_error_evidence(report)
+            status = map_node_status(report)
+            error_code = (
+                str(provider_terminal.get("error_code"))
+                if isinstance(provider_terminal.get("error_code"), str)
+                else None
+            )
+            yield CapabilityResult(
+                status=status,
+                error=exc.message if status == CapabilityStatus.FAILED else None,
+                error_code=error_code,
+                report=report,
+                node_report=report,
+            )
+            return
         except Exception as exc:
             report = self._services.build_fail_closed_report(
                 run_id=context.run_id,
@@ -385,6 +449,11 @@ class AgentAdapter:
             return
 
         report = NodeReportBuilder().build(events=events)
+        attach_agently_bridge_diagnostics(
+            report,
+            mode=getattr(self._services.config, "mode", ""),
+            requester_strategy=getattr(self._services.config, "effective_requester_strategy", "chat_completions"),
+        )
         self._apply_prompt_evidence(report=report, evidence=prompt_plan.evidence)
         _apply_on_event_error_evidence(report)
         if issues and getattr(self._services.config, "preflight_mode", "error") == "warn":
@@ -417,10 +486,20 @@ class AgentAdapter:
         )
 
         status = map_node_status(report)
+        provider_terminal = report.meta.get("provider_terminal") if isinstance(report.meta, dict) else None
+        terminal_error_code = None
+        if isinstance(provider_terminal, dict) and isinstance(provider_terminal.get("error_code"), str):
+            terminal_error_code = provider_terminal["error_code"]
+        terminal_error = None
+        if isinstance(provider_terminal, dict) and isinstance(provider_terminal.get("message"), str):
+            terminal_error = provider_terminal["message"]
+            if final_output.startswith("CAPRT_PROVIDER_STREAM_TERMINAL "):
+                final_output = terminal_error if status == CapabilityStatus.FAILED else ""
         yield CapabilityResult(
             status=status,
             output=final_output,
-            error=report.reason if status == CapabilityStatus.FAILED else None,
+            error=terminal_error if terminal_error is not None and status == CapabilityStatus.FAILED else (report.reason if status == CapabilityStatus.FAILED else None),
+            error_code=terminal_error_code,
             report=report,
             node_report=report,
             artifacts=list(report.artifacts),
@@ -578,6 +657,10 @@ class AgentAdapter:
         if messages is not None:
             evidence["prompt_messages_count"] = len(messages)
             evidence["prompt_message_roles"] = [str(item["role"]) for item in messages]
+            modalities, content_part_counts, media_count = _summarize_precomposed_message_content(messages)
+            evidence["prompt_modalities"] = modalities
+            evidence["prompt_content_part_counts"] = content_part_counts
+            evidence["prompt_media_count"] = media_count
         return evidence
 
     def _strip_runtime_prompt(self, input: Dict[str, Any]) -> Dict[str, Any]:
@@ -736,18 +819,27 @@ def _hash_text(text: str) -> str:
 def _hash_messages(messages: List[Dict[str, Any]]) -> str:
     """对 provider messages 做稳定 JSON canonicalization 后生成摘要。"""
 
-    canonical = json.dumps(messages, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    canonical = _canonicalize_messages(messages)
     return _hash_text(canonical)
 
 
+def _canonicalize_messages(messages: List[Dict[str, Any]]) -> str:
+    """对 provider messages 做稳定 JSON canonicalization。"""
+
+    try:
+        return json.dumps(messages, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False)
+    except (TypeError, ValueError) as exc:
+        raise _InvalidPromptMessages("_runtime_prompt.messages must be JSON canonicalizable") from exc
+
+
 def _validate_precomposed_messages(raw: Any) -> List[Dict[str, Any]]:
     """
     校验 host 提供的最终 provider messages。
 
     约束：
     - 只接受非空 list[dict]；
-    - 每条消息必须有合法 role 与字符串 content；
-    - 返回浅拷贝，避免后续执行链路修改调用方输入。
+    - 每条消息必须有合法 role 与字符串或稳定 content parts；
+    - 返回深拷贝，避免后续执行链路修改调用方输入。
     """
 
     if not isinstance(raw, list):
@@ -763,10 +855,92 @@ def _validate_precomposed_messages(raw: Any) -> List[Dict[str, Any]]:
         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
+        copied["content"] = _validate_precomposed_message_content(content, message_index=idx)
         out.append(copied)
+    return json.loads(_canonicalize_messages(out))
+
+
+def _validate_precomposed_message_content(content: Any, *, message_index: int) -> Union[str, List[Dict[str, Any]]]:
+    """校验单条 precomposed message 的 content 字段。"""
+
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        raise _InvalidPromptMessages(
+            f"_runtime_prompt.messages[{message_index}].content must be a string or content part list"
+        )
+    if not content:
+        raise _InvalidPromptMessages(f"_runtime_prompt.messages[{message_index}].content must not be an empty list")
+
+    out: List[Dict[str, Any]] = []
+    for part_index, part in enumerate(content):
+        out.append(_validate_precomposed_content_part(part, message_index=message_index, part_index=part_index))
     return out
+
+
+def _validate_precomposed_content_part(part: Any, *, message_index: int, part_index: int) -> Dict[str, Any]:
+    """校验 v1 稳定支持的 OpenAI-compatible content part。"""
+
+    path = f"_runtime_prompt.messages[{message_index}].content[{part_index}]"
+    if not isinstance(part, dict):
+        raise _InvalidPromptMessages(f"{path} must be a dict")
+    part_type = part.get("type")
+    if not isinstance(part_type, str) or not part_type:
+        raise _InvalidPromptMessages(f"{path}.type is required")
+    if part_type == "text":
+        if set(part.keys()) != {"type", "text"}:
+            raise _InvalidPromptMessages(f"{path} has unsupported text part fields")
+        text = part.get("text")
+        if not isinstance(text, str):
+            raise _InvalidPromptMessages(f"{path}.text must be a string")
+        return {"type": "text", "text": text}
+    if part_type == "image_url":
+        if set(part.keys()) != {"type", "image_url"}:
+            raise _InvalidPromptMessages(f"{path} has unsupported image_url part fields")
+        image_url = part.get("image_url")
+        if not isinstance(image_url, dict):
+            raise _InvalidPromptMessages(f"{path}.image_url must be a dict")
+        allowed_image_keys = {"url", "detail"}
+        if not set(image_url.keys()).issubset(allowed_image_keys):
+            raise _InvalidPromptMessages(f"{path}.image_url has unsupported fields")
+        url = image_url.get("url")
+        if not isinstance(url, str) or not url.strip():
+            raise _InvalidPromptMessages(f"{path}.image_url.url must be a non-empty string")
+        copied_image_url: Dict[str, Any] = {"url": url}
+        if "detail" in image_url:
+            detail = image_url.get("detail")
+            if detail not in _ALLOWED_IMAGE_DETAILS:
+                raise _InvalidPromptMessages(f"{path}.image_url.detail is invalid")
+            copied_image_url["detail"] = detail
+        return {"type": "image_url", "image_url": copied_image_url}
+    raise _InvalidPromptMessages(f"{path}.type is unsupported")
+
+
+def _summarize_precomposed_message_content(
+    messages: List[Dict[str, Any]],
+) -> tuple[List[str], List[int], int]:
+    """生成 precomposed messages 的最小披露多模态摘要。"""
+
+    modalities: set[str] = set()
+    content_part_counts: List[int] = []
+    media_count = 0
+    for message in messages:
+        content = message.get("content")
+        if isinstance(content, str):
+            modalities.add("text")
+            content_part_counts.append(0)
+            continue
+        if isinstance(content, list):
+            content_part_counts.append(len(content))
+            for part in content:
+                part_type = part.get("type") if isinstance(part, dict) else None
+                if part_type == "text":
+                    modalities.add("text")
+                elif part_type == "image_url":
+                    modalities.add("image")
+                    media_count += 1
+            continue
+        content_part_counts.append(0)
+    return sorted(modalities), content_part_counts, media_count