agentengine-sdk-python 0.8.5__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/harness/mcp_runtime.py

@@ -85,6 +85,14 @@ class _HealthState:
     opened_at: float | None = None
 
 
+@dataclass(frozen=True)
+class McpMetaRejection:
+    """G34：MCP _meta 策略拒绝（如 alwaysLoad 被拒）。"""
+
+    server_id: str
+    reason: str
+
+
 @dataclass
 class McpServerBinding:
     """一条 Revision binding 的运行时形态。"""
@@ -95,6 +103,9 @@ class McpServerBinding:
     required: bool = False
     #: 工具前缀（避免跨服务器重名）。
     tool_prefix: str = ""
+    #: 静态已知工具名清单（G9 §12.3.2）：连接前即可进入 L0 目录；
+    #: 外部 Server 无静态名单时为空，目录只披露 server 名 + 描述。
+    static_tool_names: tuple[str, ...] = ()
     #: ``transport`` 表示 Transport 能将幂等键透传到真正执行副作用的服务。
     #: 默认 ``none`` 保持旧 MCP Transport 行为，不虚假承诺 exactly-once。
     idempotency_mode: Literal["none", "transport"] = "none"
@@ -166,6 +177,28 @@ class McpCapabilityRuntime:
         except KeyError:
             raise McpRuntimeError(f"unknown mcp binding: {server_id}") from None
 
+    def validate_meta_policy(
+        self, *, server_id: str, meta: dict[str, Any] | None
+    ) -> "McpMetaRejection | None":
+        """G34：拒绝 MCP `_meta alwaysLoad`（被接入方不得自证跳过延迟披露）。
+
+        ``alwaysLoad``（含 ``anthropic/alwaysLoad``）让外部 Server 把整份 schema
+        塞进系统提示，绕过租户/管理员策略决定的延迟披露。返回 ``McpMetaRejection``
+        表示拒绝，None 表示接受。调用方发可见降级事件。
+        """
+        if not meta:
+            return None
+        for key, value in meta.items():
+            if key.endswith("alwaysLoad") and value:
+                return McpMetaRejection(
+                    server_id=server_id,
+                    reason=(
+                        f"_meta[{key!r}]=True 被拒绝：是否延迟披露由租户/管理员"
+                        "策略决定，不由被接入方决定（G34）"
+                    ),
+                )
+        return None
+
     def availability(self, server_id: str) -> Literal["unknown", "available", "degraded"]:
         """返回 Harness 当前观察到的 Server 可用性。
 

ksadk/harness/micro_compact.py

@@ -0,0 +1,69 @@
+"""G27 上下文减压分层（旧工具结果清壳，保留审计壳）（总案 §22 G27）。
+
+只做"清发送正文 + 保留审计壳 + 边界记账"，**不新增第二套压缩路径**：
+扫描历史消息，除最后 N 条 tool result 外，其余 tool result 的发送正文
+替换为占位壳，transcript 原文保留（审计不丢）。这是发送侧清理，不产生
+CompactionRecord，与 §25.4 约束1（保持一条阶梯）一致——清壳是一档减压，
+不是第二条摘要链。
+
+接入点：prepare_context 装配后、proactive 触发前调用，作为 proactive 之前
+的一道减压，推迟全量压缩触发。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+def _count_tokens(text: str) -> int:
+    """粗略 token 估算（字符数 / 4）；与 count_tokens 同量级即可用于记账。"""
+    return max(1, len(text) // 4)
+
+
+@dataclass
+class MicroCompactor:
+    """旧工具结果清壳器（发送侧减压，保留审计壳）。
+
+    ``keep_last_n_tool_results``：保留最近 N 条 tool result 原文，其余清壳。
+    """
+
+    keep_last_n_tool_results: int = 3
+
+    def micro_compact(
+        self, messages: list[dict[str, Any]]
+    ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+        """扫描历史，对超出 keep_last_n 的 tool result 清壳。
+
+        返回 (发送用 messages 副本, meta)；transcript 原文不动（调用方保留）。
+        meta: ``compacted_tool_ids``（被清壳的 tool_call_id）、``tokens_saved``。
+        """
+        tool_indices = [i for i, m in enumerate(messages) if m.get("role") == "tool"]
+        # 需要清壳的：除最后 N 条 tool result 之外
+        to_shell = set(tool_indices[: max(0, len(tool_indices) - self.keep_last_n_tool_results)])
+        out: list[dict[str, Any]] = []
+        compacted_ids: list[str] = []
+        tokens_saved = 0
+        for i, m in enumerate(messages):
+            if i in to_shell:
+                original = str(m.get("content") or "")
+                original_tokens = _count_tokens(original)
+                tool_name = m.get("name") or "tool"
+                shell = f"[已归档 tool:{tool_name} 结果，原文在 transcript 审计壳中]"
+                shell_tokens = _count_tokens(shell)
+                tokens_saved += max(0, original_tokens - shell_tokens)
+                compacted_ids.append(str(m.get("tool_call_id") or ""))
+                new_m = dict(m)
+                new_m["content"] = shell
+                out.append(new_m)
+            else:
+                out.append(dict(m))
+        meta = {
+            "compacted_tool_ids": compacted_ids,
+            "tokens_saved": tokens_saved,
+            "shelled_count": len(compacted_ids),
+        }
+        return out, meta
+
+
+__all__ = ["MicroCompactor"]

ksadk/harness/model_adapters/__init__.py

@@ -0,0 +1 @@
+"""Opt-in model protocol adapters; no default model/runtime registration."""

ksadk/harness/model_adapters/native_mcp_media.py

@@ -0,0 +1,100 @@
+"""Project MCP data blocks without granting URLs or payloads host authority."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from typing import Any
+
+from ksadk.harness.native.model import ModelImageContent, ModelTextContent
+from ksadk.harness.native.ports import ToolModelObservation
+
+_INLINE_CEILING = 64 * 1024 * 1024
+
+
+def _image(data: Any, mime: Any) -> ModelImageContent | None:
+    if not isinstance(data, str) or len(data) > _INLINE_CEILING:
+        return None
+    try:
+        decoded = base64.b64decode(data, validate=True)
+        matches = {
+            "image/png": decoded.startswith(b"\x89PNG\r\n\x1a\n"),
+            "image/jpeg": decoded.startswith(b"\xff\xd8\xff"),
+            "image/gif": decoded.startswith((b"GIF87a", b"GIF89a")),
+            "image/webp": decoded.startswith(b"RIFF") and decoded[8:12] == b"WEBP",
+        }
+        if not isinstance(mime, str) or not matches.get(mime, False):
+            return None
+        return ModelImageContent(image_url={"url": f"data:{mime};base64,{data}"})
+    except (ValueError, binascii.Error):
+        return None
+
+
+def model_mcp_observation(result: Any, *, failed: bool) -> ToolModelObservation | None:
+    """Preserve structured data and explicit media; never fetch an embedded URI.
+
+    Plain-text fast paths stay in native_mcp_result. This projection handles
+    the remaining protocol content, including known remote error results.
+    MIME signatures are checked, but image decoding/visual acceptance is the
+    model's job. Unsupported or invalid media is explicitly unobserved.
+    """
+    if not isinstance(result, dict) or not isinstance(result.get("content"), list):
+        return None
+    blocks = result["content"]
+    media_values: set[str] = set()
+    projected: list[ModelTextContent | ModelImageContent] = []
+    omissions = []
+    for index, block in enumerate(blocks):
+        if not isinstance(block, dict):
+            omissions.append({"block": index, "code": "mcp_content_invalid"})
+            continue
+        kind = block.get("type")
+        if kind == "text" and isinstance(block.get("text"), str):
+            projected.append(ModelTextContent(text=block["text"]))
+            continue
+        resource = block.get("resource") if kind == "resource" else None
+        data = (
+            resource.get("blob") if isinstance(resource, dict) else block.get("data")
+        )
+        if isinstance(data, str) and data:
+            media_values.add(data)
+        if isinstance(resource, dict) and isinstance(resource.get("text"), str):
+            projected.append(ModelTextContent(text=resource["text"]))
+            continue
+        mime = resource.get("mimeType") if isinstance(resource, dict) else block.get("mimeType")
+        image = _image(data, mime) if kind == "image" or isinstance(resource, dict) else None
+        if image is not None:
+            projected.extend((
+                ModelTextContent(text=f"MCP image block {index} (when available to this profile)."),
+                image,
+            ))
+        else:
+            omissions.append({"block": index, "code": "mcp_media_unobserved", "type": kind})
+
+    def without_media(value):
+        if isinstance(value, str) and value in media_values:
+            return "[MCP binary data omitted from text]"
+        if isinstance(value, list):
+            return [without_media(item) for item in value]
+        if isinstance(value, dict):
+            return {key: without_media(item) for key, item in value.items()}
+        return value
+
+    content = {
+        "kind": "mcp_tool_result",
+        "metadata": without_media({
+            key: value for key, value in result.items()
+            if key not in {"content", "structuredContent", "_meta"}
+        }),
+    }
+    if "structuredContent" in result:
+        content["structuredContent"] = without_media(result["structuredContent"])
+    if omissions:
+        content["unobserved_blocks"] = omissions
+        content["instruction"] = (
+            "Some MCP media could not be observed. Do not claim to have inspected it or "
+            "repeat the operation solely for missing media; use a supported read-only observation."
+        )
+    return ToolModelObservation(
+        status="error" if failed else "ok", content=content, content_blocks=tuple(projected),
+    )

ksadk/harness/model_adapters/native_mcp_result.py

@@ -0,0 +1,36 @@
+"""Model-facing projection of an MCP result, separate from transport status.
+
+MCP transports return typed content blocks. A plain text result should reach
+the model as that text, not as a nested SDK envelope. Preserve structured or
+non-text blocks until a host has an explicit multimodal projection for them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def model_mcp_content(result: Any) -> Any:
+    """Flatten only unambiguous text-only MCP content blocks."""
+
+    if not isinstance(result, dict):
+        return result
+    blocks = result.get("content")
+    if not isinstance(blocks, list) or not blocks:
+        return result
+    if any(
+        not isinstance(block, dict)
+        or block.get("type") != "text"
+        or not isinstance(block.get("text"), str)
+        for block in blocks
+    ):
+        return result
+    structured = result.get("structuredContent")
+    # FastMCP duplicates a scalar string in both its text block and
+    # ``structuredContent.result``. Dropping only this exact mirror avoids
+    # showing the model two nested copies of the same answer. Every other
+    # structured value remains intact for the host's richer projection.
+    duplicate_scalar = len(blocks) == 1 and structured == {"result": blocks[0]["text"]}
+    if structured not in (None, {}, []) and not duplicate_scalar:
+        return result
+    return "\n\n".join(block["text"] for block in blocks)