agentengine-sdk-python 0.8.3__py3-none-any.whl → 0.8.4__py3-none-any.whl

ksadk/studio/compiler.py

@@ -6,6 +6,8 @@ from dataclasses import dataclass
 from typing import Any
 from urllib.parse import urlparse
 
+from ksadk.plugins.providers.legacy_catalog import CODEX_AGENT_PROVIDER_PLUGIN_ID
+from ksadk.resource_runtime.plugin_config import resource_plugin_config
 from ksadk.studio.capabilities import (
     CapabilityResolver,
     LocalCapabilityResolver,
@@ -46,6 +48,39 @@ class AgentCompiler:
         self.catalog = catalog or LocalResourceCatalog(workspace)
 
     def compile(self, draft: AgentDraft) -> CompileResult:
+        unsupported_plugins = [
+            binding.plugin_ref
+            for binding in draft.spec.bindings.plugins
+            if binding.enabled
+            and resource_plugin_config(
+                binding.plugin_ref,
+                binding.ecosystem,
+                binding.config,
+                enabled=True,
+            )
+            is None
+        ]
+        if unsupported_plugins:
+            raise StudioError(
+                "NATIVE_PLUGIN_RUNTIME_INCOMPATIBLE",
+                "Framework Agent 不能直接绑定未物化的原生插件快照",
+                status_code=422,
+                field="spec.bindings.plugins",
+                details={"pluginRefs": sorted(unsupported_plugins)},
+            )
+        direct_dynamic = [
+            server.name
+            for server in draft.spec.capabilities.mcp_servers
+            if server.enabled and server.materialization == "dsh-profile"
+        ]
+        if direct_dynamic:
+            raise StudioError(
+                "DSH_MCP_MANAGED_BINDING_REQUIRED",
+                "DSH Profile MCP 必须从当前 Catalog Resource 显式绑定，不能直接写入 AgentSpec",
+                status_code=422,
+                field="spec.capabilities.mcpServers",
+                details={"servers": sorted(direct_dynamic)},
+            )
         source_payload = draft.model_dump(by_alias=True, exclude_none=True, mode="json")
         source_digest = sha256_digest(canonical_json(source_payload))
         materialized = self._materialize_bindings(draft)
@@ -62,10 +97,7 @@ class AgentCompiler:
             for ref in materialized.spec.capabilities.mcp_servers
             if ref.enabled
         ]
-        tools = [
-            self.resolver.resolve_tool(tool)
-            for tool in materialized.spec.capabilities.tools
-        ]
+        tools = [self.resolver.resolve_tool(tool) for tool in materialized.spec.capabilities.tools]
         skills.sort(key=lambda item: (item["name"], item["version"], item["digest"]))
         mcp_servers.sort(key=lambda item: (item["name"], item["version"], item["digest"]))
         tools.sort(key=lambda item: (item.name, item.version, item.digest or ""))
@@ -111,21 +143,53 @@ class AgentCompiler:
             "skills": skills,
             "mcpServers": mcp_servers,
             "tools": [
-                tool.model_dump(by_alias=True, exclude_none=True, mode="json")
-                for tool in tools
+                tool.model_dump(by_alias=True, exclude_none=True, mode="json") for tool in tools
             ],
         }
         return CompileResult(resolved=resolved, dependency_lock=dependency_lock)
 
     def _materialize_bindings(self, draft: AgentDraft) -> AgentDraft:
+        runtime = draft.spec.runtime
+        uses_codex_native_tools = bool(
+            runtime
+            and (
+                runtime.type == "codex"
+                or (
+                    runtime.type == "plugin"
+                    and runtime.provider_ref
+                    and runtime.provider_ref.startswith(
+                        f"plugin://{CODEX_AGENT_PROVIDER_PLUGIN_ID}@"
+                    )
+                )
+            )
+        )
         bindings = draft.spec.bindings
+        if uses_codex_native_tools and bindings.tools:
+            bindings = bindings.model_copy(update={"tools": []})
         if (
-            not bindings.model_profile_id
+            not uses_codex_native_tools
+            and not bindings.model_profile_id
             and not bindings.tools
             and not bindings.mcp_servers
             and not bindings.skills
         ):
             return draft
+        runtime_type = draft.spec.runtime.type if draft.spec.runtime is not None else None
+        for binding in bindings.mcp_servers:
+            if not binding.enabled:
+                continue
+            descriptor = self.catalog.get(binding.resource_id)
+            if (
+                descriptor.contract.get("materialization") == "dsh-profile"
+                and runtime_type != "harness"
+            ):
+                raise StudioError(
+                    "DSH_MCP_RUNTIME_INCOMPATIBLE",
+                    "DSH Profile MCP 当前只支持 Harness Runtime",
+                    status_code=422,
+                    field="spec.runtime.type",
+                    details={"runtimeType": runtime_type},
+                )
         materialized = draft.model_copy(deep=True)
         model = self.catalog.resolve_model(bindings) or materialized.spec.model
         if model is None:
@@ -147,9 +211,13 @@ class AgentCompiler:
                 *self.catalog.resolve_mcp_servers(bindings),
             ],
             tools=[
-                *materialized.spec.capabilities.tools,
+                *([] if uses_codex_native_tools else materialized.spec.capabilities.tools),
                 *bound_tools,
-                *bound_mcp_tools,
+                # Non-Codex runtimes consume the probed MCP contracts through
+                # the generic Tool execution path. Codex connects to the MCP
+                # server natively, so expanding those contracts here turns a
+                # valid MCP binding into unsupported third-party tools.
+                *([] if uses_codex_native_tools else bound_mcp_tools),
             ],
         )
         self._require_unique(
@@ -169,11 +237,7 @@ class AgentCompiler:
         materialized.spec.security.allowed_permissions = sorted(
             set(materialized.spec.security.allowed_permissions)
             | set(permissions)
-            | {
-                permission
-                for tool in bound_mcp_tools
-                for permission in tool.permissions
-            }
+            | {permission for tool in bound_mcp_tools for permission in tool.permissions}
         )
         endpoint = model.endpoint_url or model.base_url or ""
         hostname = (urlparse(endpoint).hostname or "").lower().rstrip(".")

ksadk/studio/contracts.py

@@ -107,9 +107,40 @@ class MCPServerRef(CapabilityRef):
     args: list[str] = Field(default_factory=list)
     endpoint_url: str | None = None
     env_refs: dict[str, str] = Field(default_factory=dict)
+    # ``dsh-profile`` is resolved at PluginHost activation time.  Only the
+    # immutable profile/inventory identity is allowed into an Agent Build;
+    # the loopback endpoint and bearer token remain process-scoped lease data.
+    materialization: Literal["dsh-profile"] | None = None
+    profile: str | None = None
+    profile_digest: str | None = None
+    descriptor_digest: str | None = None
+    inventory_digest: str | None = None
 
     @model_validator(mode="after")
     def validate_transport(self) -> "MCPServerRef":
+        dynamic_fields = (
+            self.profile,
+            self.profile_digest,
+            self.descriptor_digest,
+            self.inventory_digest,
+        )
+        if self.materialization == "dsh-profile":
+            if self.transport != "http":
+                raise ValueError("DSH Profile MCP 必须使用运行时 HTTP 租约")
+            if self.endpoint_url or self.command or self.args or self.env_refs:
+                raise ValueError("DSH Profile MCP 不能持久化 endpoint、命令或环境变量")
+            if not all(dynamic_fields):
+                raise ValueError("DSH Profile MCP 必须锁定 Profile 与能力摘要")
+            if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}", self.profile or ""):
+                raise ValueError("DSH Profile 名称无效")
+            if any(
+                not re.fullmatch(r"sha256:[0-9a-f]{64}", value or "")
+                for value in dynamic_fields[1:]
+            ):
+                raise ValueError("DSH Profile MCP 摘要无效")
+            return self
+        if any(value is not None for value in dynamic_fields):
+            raise ValueError("静态 MCP 不能声明 DSH Profile 运行时字段")
         if self.transport == "stdio" and not self.command:
             raise ValueError("stdio MCP 必须配置 command")
         if self.transport in {"http", "sse"} and not self.endpoint_url:
@@ -198,6 +229,53 @@ class CapabilityBinding(ContractModel):
     config: dict[str, Any] = Field(default_factory=dict)
 
 
+class NativePluginBinding(ContractModel):
+    """Immutable component selection from a host-managed native plugin."""
+
+    ecosystem: Literal["codex", "dsh"]
+    plugin_ref: str = Field(min_length=12, max_length=256)
+    snapshot_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    components: list[str] = Field(min_length=1, max_length=128)
+    enabled: bool = True
+    config: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("plugin_ref")
+    @classmethod
+    def validate_plugin_ref(cls, value: str) -> str:
+        if not re.fullmatch(
+            r"plugin://[a-z0-9]+(?:[._-][a-z0-9]+)*@"
+            r"\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?",
+            value,
+        ):
+            raise ValueError("插件绑定必须使用 plugin://<id>@<exact-version>")
+        return value
+
+    @field_validator("components")
+    @classmethod
+    def validate_components(cls, value: list[str]) -> list[str]:
+        if len(value) != len(set(value)):
+            raise ValueError("插件组件不能重复")
+        if any(
+            not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}", component)
+            for component in value
+        ):
+            raise ValueError("插件组件 ID 无效")
+        return value
+
+    @field_validator("config")
+    @classmethod
+    def validate_config(cls, value: dict[str, Any]) -> dict[str, Any]:
+        _reject_clear_runtime_secrets(value, path="pluginBinding.config")
+        return value
+
+    @model_validator(mode="after")
+    def validate_platform_resource_config(self) -> "NativePluginBinding":
+        from ksadk.resource_runtime.plugin_config import resource_plugin_config
+
+        resource_plugin_config(self.plugin_ref, self.ecosystem, self.config, enabled=self.enabled)
+        return self
+
+
 class AgentBindings(ContractModel):
     model_profile_id: str | None = None
     model_profile_ids: list[str] = Field(default_factory=list)
@@ -206,6 +284,7 @@ class AgentBindings(ContractModel):
     tools: list[CapabilityBinding] = Field(default_factory=list)
     mcp_servers: list[CapabilityBinding] = Field(default_factory=list)
     skills: list[CapabilityBinding] = Field(default_factory=list)
+    plugins: list[NativePluginBinding] = Field(default_factory=list)
 
     @model_validator(mode="after")
     def validate_model_profiles(self) -> "AgentBindings":
@@ -219,6 +298,12 @@ class AgentBindings(ContractModel):
             and self.model_profile_id not in self.model_profile_ids
         ):
             raise ValueError("默认 modelProfileId 必须包含在 modelProfileIds 中")
+        plugin_refs = [binding.plugin_ref for binding in self.plugins if binding.enabled]
+        if len(plugin_refs) != len(set(plugin_refs)):
+            raise ValueError("启用的插件绑定不能重复 pluginRef")
+        from ksadk.resource_runtime.plugin_config import validate_resource_plugin_bindings
+
+        validate_resource_plugin_bindings(self.plugins)
         return self
 
 
@@ -418,9 +503,7 @@ class RuntimeRef(ContractModel):
         return self
 
 
-_RUNTIME_SECRET_KEY = re.compile(
-    r"(?:secret|password|token|api[_-]?key)", re.IGNORECASE
-)
+_RUNTIME_SECRET_KEY = re.compile(r"(?:secret|password|token|api[_-]?key)", re.IGNORECASE)
 _RUNTIME_SECRET_REF_PREFIXES = (
     "secret://",
     "env://",
@@ -436,9 +519,7 @@ def _reject_clear_runtime_secrets(value: Any, *, path: str = "providerConfig") -
         for key, child in value.items():
             child_path = f"{path}.{key}"
             if _RUNTIME_SECRET_KEY.search(str(key)) and child is not None:
-                if not isinstance(child, str) or not child.startswith(
-                    _RUNTIME_SECRET_REF_PREFIXES
-                ):
+                if not isinstance(child, str) or not child.startswith(_RUNTIME_SECRET_REF_PREFIXES):
                     raise ValueError(f"{child_path} 必须保存 Secret 引用，不能保存明文")
             _reject_clear_runtime_secrets(child, path=child_path)
     elif isinstance(value, list):
@@ -460,6 +541,27 @@ class AgentSpec(ContractModel):
     security: SecuritySpec = Field(default_factory=SecuritySpec)
     evaluation: EvaluationSpec = Field(default_factory=EvaluationSpec)
 
+    @model_validator(mode="after")
+    def validate_memory_resource_reference(self) -> "AgentSpec":
+        if not self.memory.enabled or not self.memory.provider_ref.startswith("binding://"):
+            return self
+        from ksadk.resource_runtime.plugin_config import resource_plugin_config
+
+        binding_id = self.memory.provider_ref.removeprefix("binding://")
+        for binding in self.bindings.plugins:
+            if not binding.enabled:
+                continue
+            resource = resource_plugin_config(
+                binding.plugin_ref, binding.ecosystem, binding.config, enabled=True
+            )
+            if resource is not None and resource.binding.id == binding_id:
+                if resource.binding.resource.kind != "memory-instance":
+                    raise ValueError("Memory providerRef must reference a memory-instance binding")
+                if self.memory.scopes != ["user"]:
+                    raise ValueError("Platform memory requires explicit scopes: [user]")
+                return self
+        raise ValueError("Memory providerRef references a missing or disabled resource binding")
+
 
 _AGENT_ID_PATTERN = re.compile(r"^[a-z][a-z0-9-]{2,62}$")
 _AGENT_AVATAR_URL_PATTERN = re.compile(r"^/api/v1/assets/agent-avatars/[0-9a-f]{64}\.(?:png|webp)$")
@@ -638,6 +740,14 @@ class BundleManifest(ContractModel):
     composition_mode: Literal["legacy", "composed"] | None = None
     composition_profile_digest: str | None = None
     hosted_kernel_requirement_digest: str = ""
+    resource_build_digest: str | None = Field(
+        default=None,
+        pattern=r"^sha256:[0-9a-f]{64}$",
+    )
+    resource_snapshot_digest: str | None = Field(
+        default=None,
+        pattern=r"^sha256:[0-9a-f]{64}$",
+    )
     files: list[FileEntry]
     created_at: str = "1970-01-01T00:00:00Z"
     bundle_digest: str = ""
@@ -648,6 +758,10 @@ class BundleManifest(ContractModel):
             raise ValueError("composed Bundle v2 requires compositionProfileDigest")
         if self.composition_mode == "legacy" and self.composition_profile_digest:
             raise ValueError("legacy Bundle v2 cannot declare compositionProfileDigest")
+        if bool(self.resource_build_digest) != bool(self.resource_snapshot_digest):
+            raise ValueError(
+                "resourceBuildDigest and resourceSnapshotDigest must be declared together"
+            )
         return self
 
     @property
@@ -680,6 +794,14 @@ class BuildRecord(ContractModel):
     source_digest: str = ""
     runtime_lock: dict[str, Any] = Field(default_factory=dict)
     bundle_digest: str = ""
+    resource_build_digest: str | None = Field(
+        default=None,
+        pattern=r"^sha256:[0-9a-f]{64}$",
+    )
+    resource_snapshot_digest: str | None = Field(
+        default=None,
+        pattern=r"^sha256:[0-9a-f]{64}$",
+    )
     artifact_path: str | None = None
     diagnostics: list[Diagnostic] = Field(default_factory=list)
     created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
@@ -854,6 +976,10 @@ class DeploymentRequest(ContractModel):
 
 
 class DeploymentRecord(ContractModel):
+    # Identity observed when the cloud Agent was created, never inferred from
+    # whichever credentials happen to be configured when history is read.
+    created_by_name: str | None = None
+    created_by_user_id: str | None = None
     id: str
     build_id: str
     bundle_digest: str

ksadk/studio/dsh_application.py

@@ -0,0 +1,137 @@
+"""Same-origin transport for the official Core client under the Studio shell.
+
+This forwards bytes to the one supervised Core. It implements no DSH services,
+plugin protocol, settings store, or module loader.
+"""
+from __future__ import annotations
+
+import asyncio
+import hmac
+from http.cookiejar import CookieJar
+from urllib.request import HTTPCookieProcessor, ProxyHandler, build_opener
+from urllib.parse import urlsplit
+from urllib.error import URLError
+
+import httpx
+from fastapi import FastAPI, Request, WebSocket
+from starlette.background import BackgroundTask
+from starlette.responses import Response, StreamingResponse
+
+from ksadk.studio.errors import StudioError
+from ksadk.plugins.host import PluginHostError
+
+_HOP_HEADERS = {"host", "connection", "transfer-encoding", "content-length"}
+
+
+def register_dsh_application(app: FastAPI, studio, *, session_secret: str, security_enabled: bool):
+    def authorized(cookies):
+        token = cookies.get("agentkit_studio_session", "")
+        return not security_enabled or hmac.compare_digest(token, session_secret)
+
+    @app.api_route("/studio-core/", methods=["GET"])
+    async def application(request: Request):
+        if not authorized(request.cookies):
+            raise StudioError("LOCAL_SESSION_REQUIRED", "请从 Studio 启动链接进入", status_code=401)
+        try:
+            lease = await studio.dsh_capabilities.connector_lease()
+        except PluginHostError:
+            raise StudioError("DSH_CORE_UNAVAILABLE", "插件服务暂时不可用，请返回 Studio 重试", status_code=503) from None
+        def bootstrap():
+            # urllib does not log the process-token URL at INFO like httpx.
+            jar = CookieJar()
+            opener = build_opener(ProxyHandler({}), HTTPCookieProcessor(jar))
+            with opener.open(lease.browser_url(), timeout=30) as response:
+                return response.read(), tuple(jar)
+
+        try:
+            body, cookies = await asyncio.to_thread(bootstrap)
+        except (URLError, OSError):
+            # The upstream bootstrap URL contains a process token. Do not
+            # allow urllib's URL-bearing exception into API responses/logs.
+            raise StudioError("DSH_CORE_UNAVAILABLE", "插件服务连接失败，请返回 Studio 重试", status_code=503) from None
+        body = body.replace(b'<base href="/">', b'<base href="/studio-core/">')
+        result = Response(body, media_type="text/html", headers={"Cache-Control": "no-store"})
+        for cookie in cookies:
+            result.set_cookie(cookie.name, cookie.value, path=cookie.path, httponly=True, samesite="strict")
+        return result
+
+    # Registered last: the Studio API/static routes retain ownership of their paths.
+    @app.api_route("/{core_path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"])
+    async def core_http(core_path: str, request: Request):
+        if not authorized(request.cookies):
+            raise StudioError("LOCAL_SESSION_REQUIRED", "缺少有效的 Studio 本地会话", status_code=401)
+        # Retired Studio chat URLs must not start Core or depend on its availability.
+        if core_path.rstrip("/") == "chat" or core_path.startswith(("api/v1/", "v1/")):
+            raise StudioError("NOT_FOUND", "接口不存在", status_code=404)
+        # Browser mutations must originate in this document; never treat a
+        # cross-port loopback origin as trusted just because it is local.
+        if request.method not in {"GET", "HEAD"} and request.headers.get("origin") != str(request.base_url).rstrip("/"):
+            raise StudioError("LOCAL_ORIGIN_FORBIDDEN", "插件请求来源无效", status_code=403)
+        lease = await studio.dsh_capabilities.application_lease()
+        origin = lease.endpoint.rsplit("/", 1)[0]
+        path = request.url.path.removeprefix("/studio-core")
+        if request.url.query:
+            path += "?" + request.url.query
+        client = httpx.AsyncClient(trust_env=False, timeout=None)
+        headers = {key: value for key, value in request.headers.items() if key.lower() not in _HOP_HEADERS}
+        # Core checks origin against its own listening socket.
+        if "origin" in headers:
+            headers["origin"] = origin
+        try:
+            upstream = await client.send(client.build_request(request.method, origin + path, headers=headers, content=request.stream()), stream=True)
+        except BaseException:
+            await client.aclose()
+            raise
+
+        async def close():
+            await upstream.aclose()
+            await client.aclose()
+
+        result = StreamingResponse(upstream.aiter_raw(), status_code=upstream.status_code, background=BackgroundTask(close))
+        result.raw_headers = [(key, value) for key, value in upstream.headers.raw if key.decode().lower() not in _HOP_HEADERS]
+        return result
+
+    @app.websocket("/{core_path:path}")
+    async def core_socket(websocket: WebSocket, core_path: str):
+        # The SDK supports websockets 12 through 15; the legacy client is
+        # available throughout this range (the asyncio client starts at 13).
+        from websockets.legacy.client import connect
+
+        origin = websocket.headers.get("origin")
+        expected = f"http://{websocket.headers.get('host')}"
+        if not authorized(websocket.cookies) or origin != expected:
+            await websocket.close(code=1008)
+            return
+        lease = await studio.dsh_capabilities.application_lease()
+        endpoint = urlsplit(lease.endpoint)
+        path = websocket.url.path.removeprefix("/studio-core") + ("?" + websocket.url.query if websocket.url.query else "")
+        protocols = websocket.scope.get("subprotocols", [])
+        async with connect(
+            f"ws://127.0.0.1:{endpoint.port}{path}",
+            origin=f"http://127.0.0.1:{endpoint.port}",
+            extra_headers={"Cookie": websocket.headers.get("cookie", "")},
+            subprotocols=protocols or None, max_size=16 * 1024 * 1024,
+        ) as upstream:
+            await websocket.accept(subprotocol=upstream.subprotocol)
+
+            async def to_core():
+                while True:
+                    message = await websocket.receive()
+                    if message["type"] == "websocket.disconnect":
+                        return
+                    await upstream.send(message.get("text") if message.get("text") is not None else message["bytes"])
+
+            async def to_browser():
+                async for message in upstream:
+                    if isinstance(message, str):
+                        await websocket.send_text(message)
+                    else:
+                        await websocket.send_bytes(message)
+
+            tasks = [asyncio.create_task(to_core()), asyncio.create_task(to_browser())]
+            try:
+                await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+            finally:
+                for task in tasks:
+                    task.cancel()
+                await asyncio.gather(*tasks, return_exceptions=True)