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

ksadk/skills/loader.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 
 
@@ -11,6 +11,10 @@ class LocalSkill:
     root_dir: Path
     skill_md: Path
     body: str
+    # agentskills.io 标准对齐（G4）：宽容解析，未知键进 metadata 不报错。
+    metadata: dict[str, str] = field(default_factory=dict)
+    allowed_tools: tuple[str, ...] | None = None
+    warnings: tuple[str, ...] = ()
 
 
 def load_local_skill(root_dir: str | Path) -> LocalSkill:
@@ -20,12 +24,27 @@ def load_local_skill(root_dir: str | Path) -> LocalSkill:
         raise FileNotFoundError(f"SKILL.md not found: {skill_md}")
     content = skill_md.read_text(encoding="utf-8")
     metadata, body = _parse_frontmatter(content)
+    warnings: list[str] = []
+    name = metadata.get("name") or root.name
+    if metadata.get("name") and metadata["name"] != root.name:
+        warnings.append(
+            f"skill name {metadata['name']!r} 与目录名 {root.name!r} 不一致，以 frontmatter 为准"
+        )
+    allowed_tools: tuple[str, ...] | None = None
+    raw_allowed = metadata.get("allowed-tools")
+    if raw_allowed:
+        items = tuple(item.strip() for item in raw_allowed.split(",") if item.strip())
+        if items:
+            allowed_tools = items
     return LocalSkill(
-        name=metadata.get("name") or root.name,
+        name=name,
         description=metadata.get("description") or "",
         root_dir=root,
         skill_md=skill_md,
         body=body,
+        metadata=dict(metadata),
+        allowed_tools=allowed_tools,
+        warnings=tuple(warnings),
     )
 
 
@@ -44,3 +63,26 @@ def _parse_frontmatter(content: str) -> tuple[dict[str, str], str]:
         key, value = line.split(":", 1)
         metadata[key.strip()] = value.strip().strip("\"'")
     return metadata, body
+
+
+_SKIP_DIR_NAMES = frozenset({"node_modules", ".git", ".venv", "__pycache__"})
+
+
+def discover_local_skills(root: str | Path) -> list[LocalSkill]:
+    """递归发现 root 下的本地 Skill（agentskills.io 目录形态）。
+
+    标准允许嵌套目录；跳过依赖/版本控制/隐藏目录。结果按路径稳定排序。
+    """
+    root_path = Path(root)
+    if not root_path.exists():
+        raise FileNotFoundError(f"skill root not found: {root_path}")
+    skills: list[LocalSkill] = []
+    for skill_md in sorted(root_path.rglob("SKILL.md")):
+        relative_parts = skill_md.parent.relative_to(root_path).parts
+        if any(
+            part in _SKIP_DIR_NAMES or part.startswith(".")
+            for part in relative_parts
+        ):
+            continue
+        skills.append(load_local_skill(skill_md.parent))
+    return skills

ksadk/skills/runtime/backends/e2b.py

@@ -394,11 +394,9 @@ class E2BSkillRuntimeBackend:
                 )
             event_path = f"/tmp/ksadk-skill-events-{uuid4().hex}.jsonl"
             command_env = {**sandbox_env, SKILL_EVENT_FILE_ENV: event_path}
-            command = f"python -u /home/ksadk/agent.py --request-file {request_path}"
-            if pinned_packages is not None:
-                command = (
-                    f"python -I -u -m ksadk.skills.runtime.agent --request-file {request_path}"
-                )
+            command = _build_skill_command(
+                request_path=request_path, pinned=pinned_packages is not None
+            )
             output_prefix = f"/tmp/ksadk-workflow-output-{uuid4().hex}"
             stdout_path = output_prefix + ".stdout"
             stderr_path = output_prefix + ".stderr"
@@ -524,19 +522,13 @@ class E2BSkillRuntimeBackend:
                     if runtime_result is not None and (
                         runtime_result.error_type or runtime_result.timed_out
                     ):
-                        recovered_stdout = _read_output(
-                            session, stdout_path, runtime_result.stdout
-                        )
+                        recovered_stdout = _read_output(session, stdout_path, runtime_result.stdout)
                         runtime_result = replace(
                             runtime_result,
                             stdout=recovered_stdout,
                             stderr=_read_output(session, stderr_path, runtime_result.stderr),
-                            workflow_status=parse_workflow_result(
-                                recovered_stdout
-                            ).workflow_status,
-                            executed_skill=parse_workflow_result(
-                                recovered_stdout
-                            ).executed_skill,
+                            workflow_status=parse_workflow_result(recovered_stdout).workflow_status,
+                            executed_skill=parse_workflow_result(recovered_stdout).executed_skill,
                         )
                     if event_path:
                         try:
@@ -605,3 +597,14 @@ def _exception_output(exc, name: str) -> str:
     if isinstance(value, bytes):
         return value.decode("utf-8", errors="replace")
     return value if isinstance(value, str) else ""
+
+
+def _build_skill_command(*, request_path: str, pinned: bool) -> str:
+    """G34 远端 skill 禁 shell 插值：动态值经 shlex.quote，不裸拼。
+
+    request_path 含 shell 元字符（; & | $ `）也不会被 shell 当独立命令执行。
+    """
+    safe_path = shlex.quote(request_path)
+    if not pinned:
+        return f"python -u /home/ksadk/agent.py --request-file {safe_path}"
+    return f"python -I -u -m ksadk.skills.runtime.agent --request-file {safe_path}"

ksadk/skills/service_client.py

@@ -10,6 +10,7 @@ import httpx
 import requests
 
 from ksadk.common.auth import AWSV4Auth
+from ksadk.common.cloud_headers import build_cloud_headers, resolve_traffic_source
 from ksadk.skills.models import SkillListResponse, SkillRef
 
 _KOP_HOSTS = frozenset(
@@ -43,8 +44,12 @@ class SkillServiceClient:
         timeout: float = 60.0,
         transport: httpx.BaseTransport | None = None,
         allow_env_fallback: bool = True,
+        traffic_source: str | None = None,
     ):
         self.allow_env_fallback = allow_env_fallback
+        self.traffic_source = resolve_traffic_source(
+            traffic_source if traffic_source is not None or allow_env_fallback else ""
+        )
         resolve_env = _env if allow_env_fallback else lambda *names: ""
         self.base_url = _normalize_base_url(base_url)
         self.token = token
@@ -311,7 +316,7 @@ class SkillServiceClient:
                 headers["X-Action"] = action
                 headers["X-Version"] = self.api_version
         headers.update(self.extra_headers)
-        return headers
+        return build_cloud_headers(headers, traffic_source=self.traffic_source)
 
     def _get_json_kop(self, action: str, params: dict[str, Any]) -> dict[str, Any]:
         query = {"Action": action, "Version": self.api_version, **params}

ksadk/studio/a2a_bindings.py

@@ -0,0 +1,407 @@
+"""Studio A2A catalog projection, binding freeze, and drift validation."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, Literal
+
+from pydantic import Field, ValidationInfo, field_validator, model_validator
+
+from ksadk.a2a.ids import require_a2a_resource_id
+from ksadk.api import AgentEngineAPIError
+from ksadk.studio.contracts import ContractModel, RemoteAgentBinding
+from ksadk.studio.errors import StudioError
+
+_PREFIXES = {
+    "space": "a2a-space-",
+    "agent": "a2a-agent-",
+    "version": "a2a-version-",
+}
+
+
+def require_execution_policy(value: str) -> None:
+    from ksadk.a2a.policy_refs import resolve_policy_ref
+    try:
+        resolve_policy_ref(value)
+    except ValueError as exc:
+        raise StudioError("A2A_POLICY_REF_UNSUPPORTED", "A2A_POLICY_REF_UNSUPPORTED: 未知执行策略引用", status_code=422, field="policyRef") from exc
+
+
+def bindings_digest(bindings: Sequence[RemoteAgentBinding]) -> str | None:
+    from ksadk.studio.capabilities import canonical_json, sha256_digest
+
+    if not bindings:
+        return None
+    payload = [RemoteAgentBinding.model_validate(binding.model_dump()).model_dump(by_alias=True, mode="json")
+               for binding in sorted(bindings, key=lambda item: item.binding_id)]
+    return sha256_digest(canonical_json(payload))
+
+
+class A2ABindingFreezeRequest(ContractModel):
+    binding_id: str | None = Field(
+        default=None,
+        pattern=r"^a2a-binding-[0-9a-f]{32}$",
+    )
+    space_id: str
+    target_agent_id: str
+    expected_version_id: str | None = None
+    local_name: str = Field(
+        min_length=1,
+        max_length=128,
+        pattern=r"^[A-Za-z_][A-Za-z0-9_]*$",
+    )
+    exposure: Literal["native", "tool", "auto"] = "auto"
+    policy_ref: str = Field(
+        min_length=10,
+        max_length=256,
+        pattern=r"^policy://[A-Za-z0-9][A-Za-z0-9._/-]*$",
+    )
+    follow_current: bool = False
+
+    @field_validator("space_id", "target_agent_id", "expected_version_id")
+    @classmethod
+    def validate_resource_id(cls, value: str | None, info: ValidationInfo) -> str | None:
+        if value is None:
+            return None
+        prefix = {
+            "space_id": _PREFIXES["space"],
+            "target_agent_id": _PREFIXES["agent"],
+            "expected_version_id": _PREFIXES["version"],
+        }[str(info.field_name)]
+        return require_a2a_resource_id(value, prefix, field_name=str(info.field_name))
+
+    @model_validator(mode="after")
+    def validate_version_selection(self) -> "A2ABindingFreezeRequest":
+        if self.follow_current == (self.expected_version_id is not None):
+            raise ValueError("exactly one of expectedVersionId or followCurrent=true is required")
+        return self
+
+
+class A2ACatalogService:
+    """Expose only safe catalog fields from process-authenticated cloud Actions."""
+
+    def __init__(self, gateway: Callable[[], Any]) -> None:
+        self._gateway = gateway
+
+    async def list_spaces(self, *, page: int, size: int) -> dict[str, Any]:
+        data = await self._call("list_a2a_spaces", page=page, size=size)
+        items = []
+        for raw in self._list_field(data, "spaces"):
+            items.append(
+                {
+                    "spaceId": self._catalog_id("space", raw),
+                    "name": str(raw.get("name") or "").strip(),
+                    "status": str(raw.get("status") or "unknown").strip().lower(),
+                    "memberCount": self._int_field(raw, "agent_count", default=0),
+                }
+            )
+        return {
+            "items": items,
+            "total": self._int_field(data, "total_count", default=len(items)),
+            "page": self._int_field(data, "page_number", default=page),
+            "size": self._int_field(data, "page_size", default=size),
+        }
+
+    async def list_space_agents(self, space_id: str) -> dict[str, Any]:
+        canonical_space = self._canonical_input("space", space_id)
+        space = await self._call("get_a2a_space", canonical_space)
+        if self._catalog_id("space", space) != canonical_space:
+            raise self._protocol_error("space response identity mismatch")
+        if str(space.get("status") or "").lower() != "available":
+            raise StudioError("A2A_BINDING_TARGET_UNAVAILABLE", "所选 A2A Space 已不可用", status_code=409,
+                              details={"spaceId": canonical_space})
+        data = await self._call(
+            "list_a2a_space_available_agents",
+            self._wire_id("space", canonical_space),
+        )
+        items = []
+        for raw in self._list_field(data, "agents"):
+            if not self._is_callable(raw):
+                continue
+            items.append(self._agent_item(raw, space_id=canonical_space))
+        return {"items": items}
+
+    async def get_agent(self, agent_id: str) -> dict[str, Any]:
+        canonical_agent = self._canonical_input("agent", agent_id)
+        raw = await self._call(
+            "get_a2a_agent",
+            self._wire_id("agent", canonical_agent),
+        )
+        if not isinstance(raw, dict):
+            raise self._protocol_error("agent detail is not an object")
+        return {
+            "targetAgentId": self._catalog_id("agent", raw),
+            "versionId": self._canonical("version", raw.get("latest_version_id")),
+            "name": str(raw.get("name") or "").strip(),
+            "status": str(raw.get("status") or "unknown").strip().lower(),
+            "callable": self._is_callable(raw),
+        }
+
+    async def list_agent_versions(
+        self,
+        agent_id: str,
+        *,
+        page: int,
+        size: int,
+    ) -> dict[str, Any]:
+        canonical_agent = self._canonical_input("agent", agent_id)
+        data = await self._call(
+            "list_a2a_agent_versions",
+            self._wire_id("agent", canonical_agent),
+            page=page,
+            size=size,
+        )
+        items = []
+        for raw in self._list_field(data, "versions"):
+            items.append(
+                {
+                    "versionId": self._canonical("version", raw.get("version_id")),
+                    "sequence": self._int_field(raw, "sequence", default=0),
+                    "agentVersion": str(raw.get("agent_version") or "").strip(),
+                    "cardSha256": self._sha256_field(raw, "card_sha256"),
+                }
+            )
+        return {
+            "items": items,
+            "total": self._int_field(data, "total_count", default=len(items)),
+            "page": page,
+            "size": size,
+        }
+
+    async def freeze_binding(
+        self,
+        request: A2ABindingFreezeRequest,
+    ) -> RemoteAgentBinding:
+        require_execution_policy(request.policy_ref)
+        available = await self.list_space_agents(request.space_id)
+        current = next(
+            (
+                item
+                for item in available["items"]
+                if item["targetAgentId"] == request.target_agent_id
+            ),
+            None,
+        )
+        if current is None:
+            raise StudioError(
+                "A2A_BINDING_TARGET_UNAVAILABLE",
+                "远端 Agent 不在所选 Space 的可调用成员中",
+                status_code=422,
+                details={
+                    "spaceId": request.space_id,
+                    "targetAgentId": request.target_agent_id,
+                },
+            )
+        resolved_version = str(current["versionId"])
+        expected_version = request.expected_version_id or resolved_version
+        self._require_version(
+            binding_id=request.binding_id,
+            expected=expected_version,
+            actual=resolved_version,
+        )
+        return RemoteAgentBinding.freeze(
+            binding_id=request.binding_id,
+            space_id=request.space_id,
+            target_agent_id=request.target_agent_id,
+            expected_version_id=expected_version,
+            local_name=request.local_name,
+            exposure=request.exposure,
+            policy_ref=request.policy_ref,
+        )
+
+    async def validate_bindings(
+        self,
+        bindings: Sequence[RemoteAgentBinding],
+    ) -> None:
+        by_space: dict[str, dict[str, dict[str, Any]]] = {}
+        for candidate in bindings:
+            binding = RemoteAgentBinding.model_validate(candidate.model_dump())
+            require_execution_policy(binding.policy_ref)
+            if binding.space_id not in by_space:
+                listing = await self.list_space_agents(binding.space_id)
+                by_space[binding.space_id] = {
+                    item["targetAgentId"]: item for item in listing["items"]
+                }
+            current = by_space[binding.space_id].get(binding.target_agent_id)
+            if current is None:
+                raise StudioError(
+                    "A2A_BINDING_TARGET_UNAVAILABLE",
+                    "远端 Agent 已不再是可调用成员",
+                    status_code=409,
+                    details={"bindingId": binding.binding_id},
+                )
+            self._require_version(
+                binding_id=binding.binding_id,
+                expected=binding.expected_version_id,
+                actual=str(current["versionId"]),
+            )
+
+    async def _call(self, method: str, *args: Any, **kwargs: Any) -> dict[str, Any]:
+        try:
+            target = getattr(self._gateway(), method)
+            result = await target(*args, **kwargs)
+        except AgentEngineAPIError as exc:
+            if exc.code in {401, 403}:
+                raise StudioError(
+                    "A2A_CATALOG_FORBIDDEN",
+                    "当前账号无权读取 A2A 目录",
+                    status_code=403,
+                    details={"operation": method},
+                ) from exc
+            raise StudioError(
+                "A2A_CATALOG_UNAVAILABLE",
+                "远端 A2A 目录暂不可用",
+                status_code=502,
+                details={"operation": method},
+            ) from exc
+        except StudioError as exc:
+            if exc.code == "A2A_CATALOG_UNAVAILABLE":
+                raise StudioError(
+                    exc.code,
+                    "当前未配置可用的云端签名账号，不能读取 A2A 目录",
+                    status_code=exc.status_code,
+                ) from exc
+            raise StudioError(
+                "A2A_CATALOG_UNAVAILABLE",
+                "远端 A2A 目录暂不可用",
+                status_code=502,
+                details={"operation": method},
+            ) from exc
+        except Exception as exc:
+            raise StudioError(
+                "A2A_CATALOG_UNAVAILABLE",
+                "远端 A2A 目录暂不可用",
+                status_code=502,
+                details={"operation": method},
+            ) from exc
+        if not isinstance(result, dict):
+            raise self._protocol_error("catalog Action returned a non-object")
+        return result
+
+    def _catalog_id(self, kind: str, raw: Mapping[str, Any]) -> str:
+        # AgentEngineClient turns A2ASpaceId into a2_a_space_id. Some
+        # gateways already return domain snake_case; accept both explicitly.
+        names = (f"a2a_{kind}_id", f"a2_a_{kind}_id")
+        values = [self._canonical(kind, raw[name]) for name in names if name in raw]
+        if not values:
+            return self._canonical(kind, None)
+        if len(set(values)) != 1:
+            raise self._protocol_error("catalog resource identity aliases conflict")
+        return values[0]
+
+    def _canonical(self, kind: str, value: Any) -> str:
+        try:
+            return require_a2a_resource_id(
+                str(value or "").strip(), _PREFIXES[kind], field_name=kind,
+            )
+        except ValueError as exc:
+            raise StudioError(
+                "A2A_CATALOG_RESOURCE_ID_UNMAPPED",
+                "A2A 目录返回了无效的资源标识",
+                status_code=502,
+                details={"kind": kind},
+            ) from exc
+
+    def _canonical_input(self, kind: str, value: Any) -> str:
+        try:
+            return require_a2a_resource_id(
+                str(value or "").strip(), _PREFIXES[kind], field_name=kind,
+            )
+        except ValueError as exc:
+            raise StudioError(
+                "A2A_CATALOG_RESOURCE_ID_INVALID",
+                "A2A 资源标识无效",
+                status_code=422,
+                details={"kind": kind},
+            ) from exc
+
+    def _wire_id(self, kind: str, canonical: str) -> str:
+        return canonical
+
+    @classmethod
+    def _list_field(
+        cls,
+        payload: Mapping[str, Any],
+        field: str,
+    ) -> list[dict[str, Any]]:
+        raw = payload.get(field)
+        if not isinstance(raw, list) or any(not isinstance(item, dict) for item in raw):
+            raise cls._protocol_error("catalog collection field is invalid")
+        return raw
+
+    @classmethod
+    def _int_field(
+        cls,
+        payload: Mapping[str, Any],
+        field: str,
+        *,
+        default: int,
+    ) -> int:
+        raw = payload.get(field)
+        if raw is None:
+            return default
+        if isinstance(raw, bool):
+            raise cls._protocol_error("catalog numeric field is invalid")
+        try:
+            value = int(raw)
+        except (TypeError, ValueError) as exc:
+            raise cls._protocol_error("catalog numeric field is invalid") from exc
+        if value < 0:
+            raise cls._protocol_error("catalog numeric field is invalid")
+        return value
+
+    @classmethod
+    def _sha256_field(cls, payload: Mapping[str, Any], field: str) -> str:
+        value = str(payload.get(field) or "").strip().lower()
+        if re.fullmatch(r"[0-9a-f]{64}", value) is None:
+            raise cls._protocol_error("catalog digest field is invalid")
+        return value
+
+    def _agent_item(self, raw: dict[str, Any], *, space_id: str) -> dict[str, Any]:
+        card = raw.get("agent_card") if isinstance(raw.get("agent_card"), dict) else {}
+        return {
+            "spaceId": space_id,
+            "targetAgentId": self._catalog_id("agent", raw),
+            "versionId": self._canonical("version", raw.get("version_id")),
+            "name": str(card.get("name") or "").strip(),
+            "description": str(card.get("description") or "").strip(),
+            "cardSha256": self._sha256_field(raw, "card_sha256"),
+            "callable": True,
+        }
+
+    @staticmethod
+    def _is_callable(raw: Mapping[str, Any]) -> bool:
+        return (
+            str(raw.get("status") or "").strip().lower() == "available"
+            and str(raw.get("invocation_status") or "").strip().lower() == "available"
+        )
+
+    @staticmethod
+    def _require_version(*, binding_id: str | None, expected: str, actual: str) -> None:
+        if expected != actual:
+            details = {
+                "bindingId": binding_id,
+                "expectedVersionId": expected,
+                "actualVersionId": actual,
+            }
+            if binding_id is None:
+                details.pop("bindingId")
+            raise StudioError(
+                "A2A_BINDING_VERSION_DRIFT",
+                "远端 Agent 当前版本与冻结 binding 不一致",
+                status_code=409,
+                details=details,
+            )
+
+    @staticmethod
+    def _protocol_error(reason: str) -> StudioError:
+        return StudioError(
+            "A2A_CATALOG_PROTOCOL_INVALID",
+            "远端 A2A 目录响应不符合冻结合同",
+            status_code=502,
+            details={"reason": reason},
+        )
+
+
+__all__ = ["A2ABindingFreezeRequest", "A2ACatalogService"]