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

ksadk/studio/contracts.py

@@ -43,6 +43,28 @@ class Instructions(ContractModel):
     task: str = Field(default="", max_length=32768)
 
 
+class SoulDocument(ContractModel):
+    """Reviewed identity/boundary source that compiles ahead of task prompts.
+
+    This is deliberately an immutable revision input, not a mutable memory
+    file.  Runtime may read the compiled snapshot but cannot promote a new
+    SoulDocument from a conversation.
+    """
+
+    schema_version: Literal["agentkit.soul/v1"] = "agentkit.soul/v1"
+    identity: str = Field(min_length=1, max_length=4096)
+    principles: list[str] = Field(default_factory=list, max_length=64)
+    boundaries: list[str] = Field(default_factory=list, max_length=64)
+    tone: str | None = Field(default=None, max_length=1024)
+
+    @field_validator("principles", "boundaries")
+    @classmethod
+    def validate_nonempty_items(cls, value: list[str]) -> list[str]:
+        if any(not item.strip() for item in value):
+            raise ValueError("soul principles and boundaries must not contain empty items")
+        return value
+
+
 class ModelParameters(ContractModel):
     # 三者 None=未配置：请求 payload 一律不携带该字段，使用服务端默认，
     # 规避各模型族对 temperature/max_tokens 的硬约束（如 kimi 只接受默认温度）。
@@ -85,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:
@@ -176,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)
@@ -184,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":
@@ -197,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
 
 
@@ -292,6 +399,13 @@ class MemoryWriteSpec(ContractModel):
     flush_before_compaction: bool = True
 
 
+MemoryScope = Literal["tenant", "workspace", "agent", "user"]
+
+
+def _default_memory_scopes() -> list[MemoryScope]:
+    return ["workspace", "agent", "user"]
+
+
 class MemorySpec(ContractModel):
     """AgentVersion 级 Memory 策略（方案 §5.1 / §10）。Build 只存 providerRef，不存凭证。"""
 
@@ -299,9 +413,7 @@ class MemorySpec(ContractModel):
     provider_ref: str = Field(default="local-default", max_length=128)
     recall: MemoryRecallSpec = Field(default_factory=MemoryRecallSpec)
     write: MemoryWriteSpec = Field(default_factory=MemoryWriteSpec)
-    scopes: list[Literal["tenant", "workspace", "agent", "user"]] = Field(
-        default_factory=lambda: ["workspace", "agent", "user"]
-    )
+    scopes: list[MemoryScope] = Field(default_factory=_default_memory_scopes)
 
 
 class NetworkPolicy(ContractModel):
@@ -329,12 +441,17 @@ class RuntimeRef(ContractModel):
     project entrypoint that is snapshotted by its Build.
     """
 
-    type: Literal["codex", "adk", "langgraph"]
+    type: Literal["codex", "adk", "langgraph", "harness", "plugin"]
     project_path: str | None = Field(default=None, min_length=1, max_length=1024)
     entry_point: str | None = Field(default=None, min_length=1, max_length=1024)
     agent_variable: str = Field(default="root_agent", min_length=1, max_length=256)
     version: str | None = Field(default=None, min_length=1, max_length=64)
     detection: Literal["declared", "auto"] = "declared"
+    provider_ref: str | None = Field(default=None, min_length=12, max_length=256)
+    provider_config: dict[str, Any] = Field(
+        default_factory=dict,
+        exclude_if=lambda value: not value,
+    )
 
     @field_validator("project_path", "entry_point")
     @classmethod
@@ -352,8 +469,32 @@ class RuntimeRef(ContractModel):
             raise ValueError("Runtime 路径必须是工作区内的相对路径")
         return normalized
 
+    @field_validator("provider_ref")
+    @classmethod
+    def validate_provider_ref(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        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("Provider 引用必须固定为 plugin://<id>@<exact-version>")
+        return value
+
+    @field_validator("provider_config")
+    @classmethod
+    def validate_provider_config(cls, value: dict[str, Any]) -> dict[str, Any]:
+        _reject_clear_runtime_secrets(value)
+        return value
+
     @model_validator(mode="after")
     def validate_framework_source(self) -> "RuntimeRef":
+        if self.type == "plugin":
+            if not self.provider_ref:
+                raise ValueError("plugin Runtime 必须配置 providerRef")
+        elif self.provider_ref is not None or self.provider_config:
+            raise ValueError("只有 plugin Runtime 可以配置 providerRef/providerConfig")
         if self.type in {"adk", "langgraph"}:
             if not self.project_path:
                 raise ValueError(f"{self.type} Runtime 必须配置 projectPath")
@@ -362,10 +503,35 @@ class RuntimeRef(ContractModel):
         return self
 
 
+_RUNTIME_SECRET_KEY = re.compile(r"(?:secret|password|token|api[_-]?key)", re.IGNORECASE)
+_RUNTIME_SECRET_REF_PREFIXES = (
+    "secret://",
+    "env://",
+    "credential://",
+    "vault://",
+)
+
+
+def _reject_clear_runtime_secrets(value: Any, *, path: str = "providerConfig") -> None:
+    """Provider config is revision data: it may only retain secret references."""
+
+    if isinstance(value, dict):
+        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):
+                    raise ValueError(f"{child_path} 必须保存 Secret 引用，不能保存明文")
+            _reject_clear_runtime_secrets(child, path=child_path)
+    elif isinstance(value, list):
+        for index, child in enumerate(value):
+            _reject_clear_runtime_secrets(child, path=f"{path}[{index}]")
+
+
 class AgentSpec(ContractModel):
     description: str = Field(default="", max_length=1024)
     runtime: RuntimeRef | None = None
     instructions: Instructions = Field(default_factory=Instructions)
+    soul: SoulDocument | None = None
     model: ModelSpec | None = None
     capabilities: CapabilitiesSpec = Field(default_factory=CapabilitiesSpec)
     bindings: AgentBindings = Field(default_factory=AgentBindings)
@@ -375,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)$")
@@ -498,6 +685,7 @@ class ResolvedAgentSpec(ContractModel):
     source_revision: int
     compiler_version: str = "1"
     instructions: Instructions
+    soul: SoulDocument | None = None
     model: ResolvedModel
     capabilities: ResolvedCapabilities
     execution: ExecutionSpec
@@ -545,11 +733,56 @@ class BundleManifest(ContractModel):
     source_digest: str = ""
     runtime_contract: Literal["agentkit.runtime/v1"] = "agentkit.runtime/v1"
     plugin_lock_digest: str = ""
+    # A v0.8.2 bundle already used the v2 envelope without a composition.
+    # Keep that wire shape readable as the explicit legacy execution profile;
+    # newly built bundles write ``composition_mode`` so consumers never need
+    # to infer whether PluginHost admission is required from missing files.
+    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 = ""
 
+    @model_validator(mode="after")
+    def validate_composition_mode(self) -> "BundleManifest":
+        if self.composition_mode == "composed" and not self.composition_profile_digest:
+            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
+    def execution_profile(self) -> Literal["legacy", "composed"]:
+        """Normalize historical v2 manifests without rewriting their bytes.
+
+        ``compositionMode`` was added after the v0.8.2 envelope.  Its absence
+        remains a backward-compatible projection: an embedded composition
+        digest is composed; its absence selects the established runtime path.
+        """
+
+        if self.composition_mode is not None:
+            return self.composition_mode
+        return "composed" if self.composition_profile_digest else "legacy"
+
+
+# ``BundleManifest`` is the existing, installed source type.  The explicit
+# name documents that its ``agentkit.bundle/v2`` branch is the Phase 2
+# AgentBundleManifest/v2 contract; it is an alias, not a parallel manifest.
+AgentBundleManifest = BundleManifest
+
 
 class BuildRecord(ContractModel):
     id: str
@@ -561,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))
@@ -735,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)