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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capability-runtime
-Version: 0.1.3.post1
+Version: 0.1.4
 Summary: Bridge/glue layer that composes Agently (LLM/TriggerFlow) with skills-runtime-sdk (skills/tools/WAL/events).
 License-Expression: MIT
 Requires-Python: >=3.10

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

@@ -1,6 +1,6 @@
 [project]
 name = "capability-runtime"
-version = "0.1.3.post1"
+version = "0.1.4"
 description = "Bridge/glue layer that composes Agently (LLM/TriggerFlow) with skills-runtime-sdk (skills/tools/WAL/events)."
 readme = "README.md"
 requires-python = ">=3.10"

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

@@ -1,7 +1,7 @@
 """capability-runtime：统一 Runtime 入口（能力协议 + 执行 + 报告）。"""
 from __future__ import annotations
 
-__version__ = "0.1.3.post1"
+__version__ = "0.1.4"
 
 # === 统一入口 ===
 from .config import CustomTool, RuntimeConfig

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

@@ -37,6 +37,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):
@@ -578,6 +579,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 +741,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 +777,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

{capability_runtime-0.1.3.post1 → capability_runtime-0.1.4}/src/capability_runtime/sdk_lifecycle.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import hashlib
 import inspect
 import uuid
+from copy import deepcopy
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
@@ -598,12 +599,12 @@ class _PrecomposedMessagesBackend:
 
     说明：
     - 该包装不绕过 SDK Agent / WAL / events，只在 provider request 出口替换 messages；
-    - messages 做浅拷贝转发，避免下游 backend 修改 host 输入。
+    - messages 做嵌套结构副本转发，避免 host/backend 后续修改共享可变对象。
     """
 
     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]
+        self._messages: List[Dict[str, Any]] = deepcopy(messages)
 
     async def stream_chat(self, request: ChatRequest) -> AsyncGenerator[ChatStreamEvent, None]:
         """
@@ -616,7 +617,7 @@ class _PrecomposedMessagesBackend:
         forwarded = _clone_request_with_field_update(
             request,
             field_name="messages",
-            value=[dict(item) for item in self._messages],
+            value=deepcopy(self._messages),
             dataclasses_context="precomposed_messages_dataclasses_replace",
             clone_context="precomposed_messages_override",
         )

{capability_runtime-0.1.3.post1 → capability_runtime-0.1.4}/src/capability_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capability-runtime
-Version: 0.1.3.post1
+Version: 0.1.4
 Summary: Bridge/glue layer that composes Agently (LLM/TriggerFlow) with skills-runtime-sdk (skills/tools/WAL/events).
 License-Expression: MIT
 Requires-Python: >=3.10

{capability_runtime-0.1.3.post1 → capability_runtime-0.1.4}/tests/test_per_capability_llm_config_model_routing.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 - 当 llm_config 缺失/不含 model 时：不得做覆写（保持 runtime 默认行为）。
 """
 
+import copy
 from pathlib import Path
 from typing import Any, AsyncIterator, Dict, List, Optional
 
@@ -20,6 +21,7 @@ from skills_runtime.tools.protocol import ToolSpec
 from capability_runtime import AgentSpec, CapabilityKind, CapabilitySpec, CustomTool, Runtime, RuntimeConfig
 from capability_runtime.sdk_lifecycle import (
     _ModelOverrideBackend,
+    _PrecomposedMessagesBackend,
     _ResponseFormatOverrideBackend,
     _ToolChoiceOverrideBackend,
     _UsageTapBackend,
@@ -56,6 +58,28 @@ class _RecordingBackend:
         yield ChatStreamEvent(type="completed")
 
 
+class _MutatingMessagesBackend:
+    """
+    测试用 ChatBackend：记录收到的 request.messages，然后故意篡改嵌套字段。
+
+    该 backend 用于证明 `_PrecomposedMessagesBackend` 每次转发都生成独立嵌套副本，
+    下游 backend 的原地修改不会污染 lifecycle 缓存或下一次 provider request。
+    """
+
+    def __init__(self) -> None:
+        self.messages_before_mutation: List[List[Dict[str, Any]]] = []
+
+    async def stream_chat(self, request: ChatRequest) -> AsyncIterator[ChatStreamEvent]:
+        messages = getattr(request, "messages", None)
+        if isinstance(messages, list):
+            self.messages_before_mutation.append(copy.deepcopy(messages))
+            messages[1]["content"][1]["image_url"]["url"] = "https://mutated.example/image.png"
+            messages[2]["tool_calls"][0]["function"]["arguments"] = '{"mutated": true}'
+            messages[3]["metadata"]["score"] = 0
+        yield ChatStreamEvent(type="text_delta", text="ok")
+        yield ChatStreamEvent(type="completed")
+
+
 class _BrokenCloneRequest:
     """模拟 request 暴露 copy/model_copy，但内部复制总是失败。"""
 
@@ -114,6 +138,45 @@ def _agent_spec_with_prompt(
     )
 
 
+def _multimodal_messages() -> List[Dict[str, Any]]:
+    """
+    构造覆盖多模态 content parts 与 assistant/tool extra fields 的 provider messages。
+
+    返回：
+    - 可直接作为 precomposed_messages 使用的 JSON-serializable message 列表。
+    """
+
+    return [
+        {"role": "system", "content": "You inspect multimodal context."},
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "Compare the images."},
+                {"type": "image_url", "image_url": {"url": "https://example.test/a.png", "detail": "high"}},
+                {"type": "image_url", "image_url": {"url": "https://example.test/b.png"}},
+            ],
+        },
+        {
+            "role": "assistant",
+            "content": "I need the image metadata.",
+            "tool_calls": [
+                {
+                    "id": "call_1",
+                    "type": "function",
+                    "function": {"name": "inspect_image", "arguments": '{"image": "a"}'},
+                }
+            ],
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "call_1",
+            "name": "inspect_image",
+            "content": '{"width": 1280}',
+            "metadata": {"score": 1, "labels": ["diagram"]},
+        },
+    ]
+
+
 @pytest.mark.asyncio
 async def test_agent_spec_llm_config_model_overrides_backend_request_model(tmp_path: Path) -> None:
     backend = _RecordingBackend()
@@ -364,6 +427,86 @@ async def test_precomposed_messages_override_final_backend_request_messages(tmp_
     assert "Write one clean sentence" not in out.node_report.model_dump_json()
 
 
+@pytest.mark.asyncio
+async def test_precomposed_multimodal_messages_override_final_backend_request_messages(tmp_path: Path) -> None:
+    """
+    Multimodal Boundary v1：多模态 messages 与 assistant/tool extra fields 必须等价到达 backend。
+    """
+
+    backend = _RecordingBackend()
+    rt = Runtime(
+        RuntimeConfig(
+            mode="sdk_native",
+            workspace_root=tmp_path,
+            preflight_mode="off",
+            sdk_backend=backend,
+        )
+    )
+    rt.register(
+        _agent_spec_with_prompt(
+            agent_id="agent.multimodal.messages",
+            prompt_render_mode="precomposed_messages",
+            prompt_profile="generation_direct",
+        )
+    )
+    messages = _multimodal_messages()
+
+    out = await rt.run(
+        "agent.multimodal.messages",
+        input={"_runtime_prompt": {"messages": messages}},
+    )
+
+    assert out.status.value == "success"
+    assert backend.messages
+    assert messages in backend.messages
+    observed = backend.messages[-1]
+    assert observed[1]["content"] == messages[1]["content"]
+    assert observed[2]["tool_calls"] == messages[2]["tool_calls"]
+    assert observed[3]["tool_call_id"] == "call_1"
+    assert observed[3]["name"] == "inspect_image"
+    assert observed[3]["metadata"] == {"score": 1, "labels": ["diagram"]}
+
+
+@pytest.mark.asyncio
+async def test_precomposed_multimodal_messages_host_mutation_does_not_affect_request() -> None:
+    """
+    Multimodal Boundary v1：host 后续修改 nested content parts 不得污染 provider request。
+    """
+
+    backend = _RecordingBackend()
+    messages = _multimodal_messages()
+    expected = copy.deepcopy(messages)
+    wrapped = _PrecomposedMessagesBackend(backend=backend, messages=messages)
+
+    messages[1]["content"][1]["image_url"]["url"] = "https://host-mutated.example/a.png"
+    messages[2]["tool_calls"][0]["function"]["arguments"] = '{"image": "mutated"}'
+    messages[3]["metadata"]["labels"].append("host-mutated")
+
+    async for _ in wrapped.stream_chat(ChatRequest(model="test-model", messages=[])):
+        pass
+
+    assert backend.messages == [expected]
+
+
+@pytest.mark.asyncio
+async def test_precomposed_multimodal_messages_backend_mutation_does_not_pollute_next_request() -> None:
+    """
+    Multimodal Boundary v1：backend 原地修改 request.messages 不得污染 lifecycle 缓存或下一次请求。
+    """
+
+    backend = _MutatingMessagesBackend()
+    messages = _multimodal_messages()
+    expected = copy.deepcopy(messages)
+    wrapped = _PrecomposedMessagesBackend(backend=backend, messages=messages)
+
+    async for _ in wrapped.stream_chat(ChatRequest(model="test-model", messages=[])):
+        pass
+    async for _ in wrapped.stream_chat(ChatRequest(model="test-model", messages=[])):
+        pass
+
+    assert backend.messages_before_mutation == [expected, expected]
+
+
 @pytest.mark.asyncio
 async def test_prompt_profile_generation_direct_reaches_sdk_prompt_config_and_hides_tools(
     tmp_path: Path,

{capability_runtime-0.1.3.post1 → capability_runtime-0.1.4}/tests/test_release_tag_version_guardrail.py

@@ -22,11 +22,11 @@ def _load_release_guard_module():
 def test_release_guard_accepts_current_tag() -> None:
     module = _load_release_guard_module()
     tag_version, pyproject_version, module_version = module.validate_versions(
-        release_tag="v0.1.3.post1",
+        release_tag="v0.1.4",
         pyproject_path=_REPO_ROOT / "pyproject.toml",
         init_path=_REPO_ROOT / "src" / "capability_runtime" / "__init__.py",
     )
-    assert tag_version == pyproject_version == module_version == "0.1.3.post1"
+    assert tag_version == pyproject_version == module_version == "0.1.4"
 
 
 def test_release_guard_rejects_mismatch() -> None: