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

ksadk/studio/model_profile_service.py

@@ -96,6 +96,31 @@ def _classify_probe(status_code: int) -> str:
     return "error"
 
 
+def _recommended_probe(attempts: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """Choose the profile protocol from probe results deterministically.
+
+    Responses is preferred for a generic URL when both endpoints are usable;
+    an explicitly supplied endpoint still produces a single eligible result.
+    """
+    protocol_priority = {"responses": 0, "chat": 1}
+    for wanted in ("ok", "auth_required", "recognized"):
+        eligible = [a for a in attempts if a.get("status") == wanted]
+        hit = min(
+            eligible,
+            key=lambda attempt: protocol_priority.get(str(attempt.get("protocol")), 99),
+            default=None,
+        )
+        if hit is not None:
+            protocol = str(hit["protocol"])
+            return {
+                "protocol": protocol,
+                "wireApi": "responses" if protocol == "responses" else "chat",
+                "endpointUrl": hit["endpointUrl"],
+                "status": hit["status"],
+            }
+    return None
+
+
 async def probe_model_endpoint(
     *,
     url: str,
@@ -190,17 +215,7 @@ async def probe_model_endpoint(
             *(_post(client, protocol, endpoint, probe_model) for protocol, endpoint in candidates)
         )
 
-    recommended: dict[str, Any] | None = None
-    for wanted in ("ok", "auth_required", "recognized"):
-        hit = next((a for a in attempts if a["status"] == wanted), None)
-        if hit is not None:
-            recommended = {
-                "protocol": hit["protocol"],
-                "wireApi": "responses" if hit["protocol"] == "responses" else "chat",
-                "endpointUrl": hit["endpointUrl"],
-                "status": hit["status"],
-            }
-            break
+    recommended = _recommended_probe(attempts)
 
     return {
         "input": url,

ksadk/studio/native_documents.py

@@ -0,0 +1,172 @@
+"""User-triggered desktop actions for verified, run-owned workspace documents.
+
+The browser supplies a run and relative document reference, never an executable
+or absolute filesystem path. Native actions belong to the computer running the
+local Studio process; remote/proxied clients retain the download fallback.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Literal
+from urllib.parse import urlparse
+
+from fastapi import Request
+from pydantic import BaseModel, ConfigDict, Field
+
+from ksadk.studio.errors import StudioError
+from ksadk.studio.run_documents import read_document
+
+
+class NativeDocumentActionRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    path: str = Field(min_length=1, max_length=1024)
+    action: Literal["open", "reveal"]
+    application_id: str | None = Field(default=None, alias="applicationId", max_length=64)
+
+
+# Explicit desktop application allowlist. Do not accept program names, bundle
+# identifiers, arguments or arbitrary application paths from browser input.
+_MAC_APPLICATIONS = (
+    ("vscode", "Visual Studio Code", "Visual Studio Code.app"),
+    ("cursor", "Cursor", "Cursor.app"),
+    ("typora", "Typora", "Typora.app"),
+    ("markedit", "MarkEdit", "MarkEdit.app"),
+    ("bbedit", "BBEdit", "BBEdit.app"),
+    ("coteditor", "CotEditor", "CotEditor.app"),
+    ("textedit", "TextEdit", "TextEdit.app"),
+)
+
+
+def _loopback(host: str | None) -> bool:
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host or "").is_loopback
+    except ValueError:
+        return False
+
+
+def is_local_desktop_request(request: Request) -> bool:
+    """Fail closed for remote peers/proxies even when the Host looks local."""
+    if not request.client or not _loopback(request.client.host):
+        return False
+    if not _loopback(request.url.hostname):
+        return False
+    if any(
+        key.lower() == "forwarded" or key.lower().startswith("x-forwarded-")
+        for key in request.headers
+    ):
+        return False
+    origin = request.headers.get("origin")
+    if origin:
+        parsed = urlparse(origin)
+        if (parsed.scheme, parsed.netloc) != (request.url.scheme, request.url.netloc):
+            return False
+    return True
+
+
+def _desktop_launcher() -> str | None:
+    if sys.platform == "darwin":
+        return "/usr/bin/open" if Path("/usr/bin/open").is_file() else None
+    if sys.platform.startswith("linux") and (
+        os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")
+    ):
+        return shutil.which("xdg-open")
+    return None
+
+
+def _application_roots() -> tuple[Path, ...]:
+    return (Path("/Applications"), Path.home() / "Applications", Path("/System/Applications"))
+
+
+def _installed_applications() -> dict[str, tuple[str, Path]]:
+    if sys.platform != "darwin":
+        return {}
+    applications = {}
+    for app_id, name, bundle in _MAC_APPLICATIONS:
+        for root in _application_roots():
+            path = root / bundle
+            if path.is_dir():
+                applications[app_id] = (name, path)
+                break
+    return applications
+
+
+def document_metadata(studio, run_id: str, name: str, *, local: bool) -> dict:
+    path, _ = read_document(studio, run_id, name)
+    supported = local and _desktop_launcher() is not None
+    applications = _installed_applications() if supported else {}
+    return {
+        "name": path.name,
+        "path": str(path) if local else None,
+        "relativePath": name,
+        "platform": sys.platform,
+        "capabilities": {
+            "open": supported,
+            "reveal": supported,
+            "openWith": bool(applications),
+        },
+        "applications": [{"id": app_id, "name": app[0]} for app_id, app in applications.items()],
+        "revealLabel": "在 Finder 中显示" if sys.platform == "darwin" else "打开所在文件夹",
+    }
+
+
+def _launch(command: list[str]) -> None:
+    # No shell, no detached script and no raw browser-supplied arguments.
+    subprocess.run(
+        command,
+        check=True,
+        timeout=10,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+
+def perform_document_action(
+    studio, run_id: str, payload: NativeDocumentActionRequest, *, local: bool
+) -> dict:
+    if not local:
+        raise StudioError(
+            "NATIVE_DOCUMENT_LOCAL_ONLY",
+            "仅本机直连 Studio 支持打开电脑中的文件；请下载后打开。",
+            status_code=403,
+        )
+    path, _ = read_document(studio, run_id, payload.path)
+    launcher = _desktop_launcher()
+    if launcher is None:
+        raise StudioError(
+            "NATIVE_DOCUMENT_UNAVAILABLE",
+            "当前 Studio 没有可用的桌面环境，请下载后打开。",
+            status_code=409,
+        )
+    application = None
+    if payload.application_id is not None:
+        application = _installed_applications().get(payload.application_id)
+        if payload.action != "open" or application is None:
+            raise StudioError(
+                "DOCUMENT_APPLICATION_UNAVAILABLE", "所选打开方式不可用。", status_code=422
+            )
+    try:
+        if sys.platform == "darwin":
+            command = [launcher]
+            if payload.action == "reveal":
+                command += ["-R"]
+            elif application is not None:
+                command += ["-a", str(application[1])]
+            _launch([*command, str(path)])
+        else:
+            _launch([launcher, str(path if payload.action == "open" else path.parent)])
+    except (OSError, subprocess.SubprocessError) as error:
+        # Native launcher stderr may include unrelated local paths and details.
+        raise StudioError(
+            "DOCUMENT_OPEN_FAILED", "系统未能打开文件，请选择其他打开方式或下载。", status_code=502
+        ) from error
+    return {"status": "opened" if payload.action == "open" else "revealed", "name": path.name}

ksadk/studio/plugin_composition.py

@@ -1,6 +1,6 @@
 """Studio Agent revision -> immutable PluginHost composition binding.
 
-This is the production build seam for Phase 2.  It admits built-in providers
+This is the production build seam for Release.  It admits built-in providers
 or one exact AgentProvider registration emitted by the active DSH host,
 then delegates the deterministic Profile/Lock construction to
 ``CompositionCompiler``.  Legacy ADK/LangGraph drafts intentionally bypass
@@ -9,12 +9,16 @@ this module and retain their established source-build behavior.
 
 from __future__ import annotations
 
+import re
 from collections.abc import Mapping
 from copy import deepcopy
+from dataclasses import replace
 
+from ksadk.harness.tools import HARNESS_SANDBOX_TOOL_NAMES
 from ksadk.plugins.builtins import (
     BUILTIN_PLUGIN_VERSION,
     CORE_RENDERER_PLUGIN_ID,
+    LOCAL_MEMORY_PROVIDER_PLUGIN_ID,
     READ_ONLY_CONTEXT_PLUGIN_ID,
     SQLITE_SESSION_STORE_PLUGIN_ID,
     WORKSPACE_MCP_PLUGIN_ID,
@@ -30,14 +34,28 @@ from ksadk.plugins.composition import (
     RuntimePluginSelection,
 )
 from ksadk.plugins.contracts import PluginManifest
+from ksadk.plugins.providers.dsh_mcp import (
+    DSH_PROFILE_MCP_PLUGIN_ID,
+    DSH_PROFILE_MCP_PLUGIN_VERSION,
+    DSH_PROFILE_TOOL_PERMISSION,
+    dsh_harness_tool_alias,
+    dsh_profile_mcp_manifest,
+)
 from ksadk.plugins.providers.legacy_catalog import (
     BUILTIN_PROVIDER_VERSION,
     KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID,
     builtin_agent_provider_manifests,
 )
+from ksadk.plugins.providers.platform_resources import (
+    PLATFORM_RESOURCE_MCP_REF,
+    platform_resource_mcp_manifest,
+)
 from ksadk.plugins.resolver import PluginRegistry, ResolvedComposition
+from ksadk.resource_runtime.plugin_config import resource_plugin_config
+from ksadk.studio.capabilities import canonical_json, sha256_digest
 from ksadk.studio.contracts import AgentDraft, CapabilityBinding
 from ksadk.studio.errors import StudioError
+from ksadk.studio.resource_build_admission import resource_build_required
 from ksadk.studio.resource_catalog import LocalResourceCatalog
 from ksadk.studio.workspace import Workspace
 
@@ -109,7 +127,11 @@ class StudioPluginCompositionCompiler:
         manifests = [
             *builtin_agent_provider_manifests(),
             *builtin_capability_manifests(),
+            dsh_profile_mcp_manifest(),
         ]
+        requires_platform_resources = resource_build_required(draft)
+        if requires_platform_resources:
+            manifests.append(platform_resource_mcp_manifest())
         harness_ref = _plugin_ref(
             KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID,
             BUILTIN_PROVIDER_VERSION,
@@ -142,15 +164,24 @@ class StudioPluginCompositionCompiler:
                 "session.events",
             ),
             resource_materializations=self._resource_materializations(draft),
+            memory_providers=self._memory_providers(draft),
+            host_capabilities=(
+                PluginCapabilitySelection(
+                    ref=PLATFORM_RESOURCE_MCP_REF,
+                    definition="mcp.connector/v1",
+                    slot="mcp.platform-resources",
+                    config={"artifactPath": "platform-resources"},
+                ),
+            )
+            if requires_platform_resources
+            else (),
             context_contributors={
                 "workspace_rules": _selection(
                     READ_ONLY_CONTEXT_PLUGIN_ID,
                     "context.contributor/v1",
                     "context.bundle",
                     config={
-                        "paths": ["instructions/soul.md"]
-                        if draft.spec.soul is not None
-                        else [],
+                        "paths": ["instructions/soul.md"] if draft.spec.soul is not None else [],
                         "maxChars": draft.spec.context.max_input_tokens * 4,
                     },
                 )
@@ -165,9 +196,18 @@ class StudioPluginCompositionCompiler:
             default_runtime="harness",
         )
         try:
-            return CompositionCompiler(
+            resolved = CompositionCompiler(
                 PluginRegistry(manifests), self._catalog, policy
             ).compile(draft)
+            source_payload = draft.model_dump(
+                by_alias=True,
+                exclude_none=True,
+                mode="json",
+            )
+            return replace(
+                resolved,
+                source_digest=sha256_digest(canonical_json(source_payload)),
+            )
         except CompositionCompileError as error:
             raise StudioError(
                 error.code.upper(),
@@ -217,10 +257,7 @@ class StudioPluginCompositionCompiler:
                 status_code=422,
                 field="spec.runtime.providerRef",
             )
-        if (
-            manifest.metadata.id != plugin_id
-            or manifest.metadata.version != version
-        ):
+        if manifest.metadata.id != plugin_id or manifest.metadata.version != version:
             raise StudioError(
                 "AGENT_PROVIDER_REGISTRATION_MISMATCH",
                 "DSH AgentProvider 注册信息与精确引用不一致",
@@ -228,15 +265,9 @@ class StudioPluginCompositionCompiler:
                 field="spec.runtime.providerRef",
             )
         offers = [
-            offer
-            for offer in manifest.spec.provides
-            if offer.definition == _PROVIDER_DEFINITION
+            offer for offer in manifest.spec.provides if offer.definition == _PROVIDER_DEFINITION
         ]
-        if (
-            len(offers) != 1
-            or offers[0].slot != _PROVIDER_SLOT
-            or offers[0].mode != "unique"
-        ):
+        if len(offers) != 1 or offers[0].slot != _PROVIDER_SLOT or offers[0].mode != "unique":
             raise StudioError(
                 "AGENT_PROVIDER_MANIFEST_INVALID",
                 "插件必须唯一提供 agent.provider/v1 的 agent.execution 槽位",
@@ -251,8 +282,7 @@ class StudioPluginCompositionCompiler:
                 field="spec.runtime.providerRef",
             )
         missing_permissions = sorted(
-            set(manifest.spec.permissions)
-            - set(draft.spec.security.allowed_permissions)
+            set(manifest.spec.permissions) - set(draft.spec.security.allowed_permissions)
         )
         if missing_permissions:
             raise StudioError(
@@ -288,14 +318,162 @@ class StudioPluginCompositionCompiler:
                         field=f"spec.bindings.{kind}",
                         details={"resourceId": binding.resource_id},
                     )
-                plugin_id = (
-                    WORKSPACE_MCP_PLUGIN_ID if kind == "mcp" else WORKSPACE_SKILL_PLUGIN_ID
-                )
+                config = deepcopy(binding.config)
+                if kind == "mcp" and descriptor.contract.get("materialization") == "dsh-profile":
+                    if binding.approval != "never":
+                        raise StudioError(
+                            "DSH_MCP_AUTONOMOUS_APPROVAL_REQUIRED",
+                            "Harness 尚不支持 DSH 工具逐调用审批；必须显式允许自主调用",
+                            status_code=422,
+                            field="spec.bindings.mcpServers.approval",
+                        )
+                    unknown = sorted(set(config) - {"toolFilter", "toolNamePrefix"})
+                    if unknown:
+                        raise StudioError(
+                            "DSH_MCP_BINDING_CONFIG_INVALID",
+                            "DSH MCP 绑定只支持 toolFilter 与 toolNamePrefix",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                            details={"unknownFields": unknown},
+                        )
+                    tool_filter = config.get("toolFilter")
+                    if (
+                        not isinstance(tool_filter, list)
+                        or not tool_filter
+                        or any(
+                            not isinstance(item, str) or not item.strip() for item in tool_filter
+                        )
+                        or len(tool_filter) != len(set(tool_filter))
+                        or len(tool_filter) > 32
+                        or sum(len(item.encode("utf-8")) for item in tool_filter) > 2048
+                    ):
+                        raise StudioError(
+                            "DSH_MCP_TOOL_FILTER_REQUIRED",
+                            "DSH MCP 绑定必须显式选择至少一个且不重复的工具",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                        )
+                    tool_filter = [item.strip() for item in tool_filter]
+                    config["toolFilter"] = tool_filter
+                    known_tools = {
+                        str(item.get("name"))
+                        for item in descriptor.contract.get("discoveredTools") or []
+                        if isinstance(item, Mapping)
+                    }
+                    unknown_tools = sorted(set(tool_filter) - known_tools)
+                    if unknown_tools:
+                        raise StudioError(
+                            "DSH_MCP_TOOL_FILTER_INVALID",
+                            "DSH MCP toolFilter 包含当前 Profile 不存在的工具",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                            details={"unknownTools": unknown_tools},
+                        )
+                    if DSH_PROFILE_TOOL_PERMISSION not in draft.spec.security.allowed_permissions:
+                        raise StudioError(
+                            "DSH_MCP_HOST_PERMISSION_REQUIRED",
+                            "DSH Profile 工具在宿主用户权限下运行，必须显式授权",
+                            status_code=422,
+                            field="spec.security.allowedPermissions",
+                            details={"missingPermissions": [DSH_PROFILE_TOOL_PERMISSION]},
+                        )
+                    prefix = config.get("toolNamePrefix")
+                    if prefix is not None and (
+                        not isinstance(prefix, str)
+                        or not prefix.strip()
+                        or len(prefix.strip()) > 16
+                        or re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,15}", prefix.strip()) is None
+                    ):
+                        raise StudioError(
+                            "DSH_MCP_BINDING_CONFIG_INVALID",
+                            "DSH MCP toolNamePrefix 必须是 1-16 个字母、数字、下划线或连字符",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                        )
+                    prefix = prefix.strip() if isinstance(prefix, str) else None
+                    aliases = [dsh_harness_tool_alias(name, prefix) for name in tool_filter]
+                    if len(aliases) != len(set(aliases)):
+                        raise StudioError(
+                            "DSH_MCP_TOOL_ALIAS_COLLISION",
+                            "所选 DSH 工具映射为模型工具名后发生冲突",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                        )
+                    reserved_aliases = sorted(set(aliases) & HARNESS_SANDBOX_TOOL_NAMES)
+                    if reserved_aliases:
+                        raise StudioError(
+                            "DSH_MCP_TOOL_ALIAS_RESERVED",
+                            "DSH 工具名与 Harness 内置 sandbox 工具冲突，请设置 toolNamePrefix",
+                            status_code=422,
+                            field="spec.bindings.mcpServers",
+                            details={"reservedAliases": reserved_aliases},
+                        )
+                    config["toolNamePrefix"] = prefix
+                    plugin_id = DSH_PROFILE_MCP_PLUGIN_ID
+                    plugin_version = DSH_PROFILE_MCP_PLUGIN_VERSION
+                    config.update(
+                        {
+                            "profile": descriptor.contract.get("profile"),
+                            "profileDigest": descriptor.contract.get("profileDigest"),
+                            "descriptorDigest": descriptor.contract.get("descriptorDigest"),
+                            "inventoryDigest": descriptor.contract.get("inventoryDigest"),
+                        }
+                    )
+                else:
+                    plugin_id = (
+                        WORKSPACE_MCP_PLUGIN_ID if kind == "mcp" else WORKSPACE_SKILL_PLUGIN_ID
+                    )
+                    plugin_version = BUILTIN_PLUGIN_VERSION
                 materializations[binding.resource_id] = ResourcePluginMaterialization(
                     kind=kind,  # type: ignore[arg-type]
-                    plugin_ref=_plugin_ref(plugin_id, BUILTIN_PLUGIN_VERSION),
-                    config=deepcopy(binding.config),
+                    plugin_ref=_plugin_ref(plugin_id, plugin_version),
+                    config=config,
                 )
         return materializations
 
+    @staticmethod
+    def _memory_providers(
+        draft: AgentDraft,
+    ) -> dict[str, PluginCapabilitySelection]:
+        """Materialize a bound platform memory through its official DSH owner."""
+
+        memory = draft.spec.memory
+        if not memory.enabled:
+            return {}
+        if memory.provider_ref == "local-default":
+            return {
+                memory.provider_ref: _selection(
+                    LOCAL_MEMORY_PROVIDER_PLUGIN_ID,
+                    "memory.provider/v1",
+                    "memory.primary",
+                )
+            }
+        if not memory.provider_ref.startswith("binding://"):
+            return {}
+        binding_id = memory.provider_ref.removeprefix("binding://")
+        for binding in draft.spec.bindings.plugins:
+            if not binding.enabled:
+                continue
+            config = resource_plugin_config(
+                binding.plugin_ref,
+                binding.ecosystem,
+                binding.config,
+                enabled=True,
+            )
+            if (
+                config is not None
+                and config.binding.id == binding_id
+                and config.binding.resource.kind == "memory-instance"
+            ):
+                return {
+                    memory.provider_ref: PluginCapabilitySelection(
+                        ref=PLATFORM_RESOURCE_MCP_REF,
+                        definition="memory.provider/v1",
+                        slot="memory.primary",
+                        config={"artifactPath": "platform-resources"},
+                    )
+                }
+        return {}
+
+
 __all__ = ["StudioPluginCompositionCompiler"]