agentengine-sdk-python 0.8.4__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
@@ -18,6 +18,7 @@ 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,
@@ -437,7 +438,17 @@ class StudioPluginCompositionCompiler:
         """Materialize a bound platform memory through its official DSH owner."""
 
         memory = draft.spec.memory
-        if not memory.enabled or not memory.provider_ref.startswith("binding://"):
+        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:

ksadk/studio/plugin_kernel_adapter.py

@@ -12,6 +12,11 @@ class StudioPluginKernelAdapter(PluginKernelAdapter):
     """Bind a Studio Build/session to its profile-fenced provider activation."""
 
     def __init__(self, plugin_runtime: Any, spec: StudioRunSpec) -> None:
+        self._policy_supported = (
+            spec.request_config.get("provider_runtime_type") == "harness"
+            and getattr(plugin_runtime, "execution_policy_resolver", None) is not None
+        )
+
         async def bind_delegate(session_id: str):  # type: ignore[no-untyped-def]
             return await plugin_runtime.kernel_adapter(spec, session_id=session_id)
 
@@ -24,5 +29,15 @@ class StudioPluginKernelAdapter(PluginKernelAdapter):
             release_binding=release_binding,
         )
 
+    def capabilities(self):  # type: ignore[no-untyped-def]
+        # Studio wires a durable Workspace store before activating Harness.
+        if self._delegate is None and self._runtime_type == "harness":
+            from ksadk.harness.managed_runtime import managed_harness_capabilities
+
+            return managed_harness_capabilities(
+                durable=True, execution_policy=self._policy_supported,
+            )
+        return super().capabilities()
+
 
 __all__ = ["StudioPluginKernelAdapter"]

ksadk/studio/plugin_lifecycle.py

@@ -0,0 +1,80 @@
+"""Credential-free failures shared by local plugin lifecycle surfaces."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ksadk.studio.errors import StudioError
+
+RECOVERY_URL = "/studio-recovery/"
+_MESSAGES = {
+    "DSH_PROFILE_IN_USE": "仍有执行或审批正在进行，请结束执行后再变更插件 Profile。",
+    "authority_in_use": "已有本地宿主占用团队存储；请等待原宿主退出后重试。",
+    "artifact_migration_required": (
+        "插件版本已更新，需要先检查旧团队数据。已结束的兼容历史可以备份升级。"
+    ),
+    "migration_active_runs": "仍有在途任务，请先恢复原版本并核对执行状态，再升级历史。",
+    "local_upgrade_unsupported": "此历史版本需要专门迁移，请保留备份并使用原锁定版本。",
+    "migration_uncertain_execution": "仍有结果未确认的执行，请先核查原单再迁移。",
+    "execution_node_in_use": "这个工作区已有执行节点在运行，请等待其退出后重试。",
+    "DSH_TOOLCHAIN_MISSING": "本地插件工具链缺失，请先安装或修复 DSH。",
+    "dsh_toolchain_required": "本地插件工具链尚未配置，请先安装并启用 DSH。",
+    "teams_credentials_required": "团队服务连接凭据不可用，请更新本地配置后重试。",
+    "COMPANION_GRAPH_INCOMPLETE": "团队插件组件不完整，请修复或禁用插件。",
+    "COMPANION_GRAPH_NOT_READY": "团队插件组件尚未就绪，请重试或禁用插件。",
+}
+_REQUIRES_CHANGE = {
+    "artifact_migration_required",
+    "artifact_required",
+    "artifact_scope_mismatch",
+    "COMPANION_GRAPH_INCOMPLETE",
+    "COMPANION_PROFILE_MISMATCH",
+    "DSH_HOME_VERSION_UNVERIFIED",
+    "DSH_TOOLCHAIN_MISSING",
+    "authority_profile_unavailable",
+    "dsh_toolchain_required",
+}
+
+
+def lifecycle_failure(error: BaseException, stage: str) -> dict[str, Any]:
+    """Never expose exception text, transport addresses, or credentials."""
+    code = getattr(error, "code", "plugin_lifecycle_failed")
+    if not isinstance(code, str) or not re.fullmatch(r"[A-Za-z0-9_.-]{1,96}", code):
+        code = "plugin_lifecycle_failed"
+    details = getattr(error, "details", {})
+    prior_stage = details.get("stage") if isinstance(details, dict) else None
+    if isinstance(prior_stage, str) and re.fullmatch(r"[a-z_]{1,64}", prior_stage):
+        stage = prior_stage
+    reason = details.get("reason") if isinstance(details, dict) else None
+    if not isinstance(reason, str) or not re.fullmatch(r"[A-Za-z0-9_.-]{1,96}", reason):
+        reason = None
+    return {
+        "code": code,
+        "message": _MESSAGES.get(code, "插件暂时不可用，请查看诊断信息或重试。"),
+        "stage": stage,
+        "retryable": (reason or code) not in _REQUIRES_CHANGE,
+        "recoveryUrl": RECOVERY_URL,
+        **({"reason": reason} if reason else {}),
+    }
+
+
+def lifecycle_error(error: BaseException, stage: str) -> StudioError:
+    failure = lifecycle_failure(error, stage)
+    if isinstance(error, StudioError):
+        return StudioError(
+            error.code,
+            error.message,
+            status_code=error.status_code,
+            field=error.field,
+            details={**error.details, **failure},
+        )
+    status = getattr(error, "status", 503)
+    if not isinstance(status, int) or not 400 <= status <= 599:
+        status = 503
+    return StudioError(
+        failure["code"],
+        _MESSAGES.get(failure["code"], "插件未能完成装配，请打开恢复页面查看状态。"),
+        status_code=status,
+        details=failure,
+    )