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

ksadk/studio/dsh_lifecycle.py

@@ -0,0 +1,58 @@
+"""DSH startup diagnostics and companion lifecycle shared by Studio entry points."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from ksadk.plugins.companions import CompanionError, DshCompanionDefinition, DshPluginCompanionManager
+from ksadk.plugins.providers.dsh_capabilities import DshProfileCapabilityHost, DshMcpConnectorLease
+from ksadk.studio.plugin_lifecycle import RECOVERY_URL, lifecycle_error, lifecycle_failure
+
+
+class DshStartupLifecycle:
+    @property
+    def startup_status(self) -> dict[str, Any]:
+        """Inspect lifecycle without booting Core or resolving credentials."""
+        return {
+            "state": "closed" if self._closed else "failed" if self._startup_failure else (
+                "ready" if self._lease is not None else "not_ready"
+            ),
+            "stage": self._startup_stage,
+            "failure": dict(self._startup_failure) if self._startup_failure else None,
+            "generationId": self._generation_id,
+            "recoveryUrl": RECOVERY_URL,
+        }
+
+
+    def configure_companions(self, definitions: Sequence[DshCompanionDefinition]) -> None:
+        """Configure trusted lifecycle callbacks before this Profile starts."""
+        if self._host is not None or self._closed:
+            raise CompanionError("COMPANION_CONFIGURATION_BUSY")
+        if any(item.profile != self._profile for item in definitions):
+            raise CompanionError("COMPANION_PROFILE_MISMATCH")
+        self._companion_definitions = tuple(definitions)
+
+
+    @property
+    def companion_manager(self) -> DshPluginCompanionManager | None:
+        return self._companion_manager
+
+
+    async def _ensure_ready_locked(
+        self,
+    ) -> tuple[DshProfileCapabilityHost, DshMcpConnectorLease]:
+        try:
+            result = await self._ensure_ready_generation_locked()
+        except Exception as error:
+            self._startup_failure = lifecycle_failure(error, self._startup_stage)
+            raise lifecycle_error(error, self._startup_stage) from error
+        self._startup_failure = None
+        self._startup_stage = "ready"
+        return result
+
+
+    async def _close_companions_locked(self) -> None:
+        manager, self._companion_manager = self._companion_manager, None
+        if manager is not None:
+            await manager.close()

ksadk/studio/dsh_mcp_transport.py

@@ -0,0 +1,191 @@
+"""HTTP/JSON-RPC mechanics for Studio's generation-bound DSH MCP lease.
+
+The service retains lifecycle, cancellation ownership, limits and generation
+locks. These overridable methods only perform requests on its existing lease.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from collections.abc import Mapping
+from typing import Any, Literal, cast
+
+import httpx
+
+from ksadk.plugins.providers.dsh_capabilities import (
+    DSH_CAPABILITY_BUNDLE_PACKAGE,
+    DSH_CAPABILITY_HOST_VERSION,
+    DSH_CAPABILITY_MCP_PROTOCOL,
+    DshMcpConnectorLease,
+)
+from ksadk.studio.errors import StudioError
+
+
+def _duplicate_rejecting_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    value: dict[str, Any] = {}
+    for key, item in pairs:
+        if key in value:
+            raise ValueError("duplicate JSON member")
+        value[key] = item
+    return value
+
+
+def _reject_non_finite(value: str) -> None:
+    raise ValueError(f"non-finite JSON number: {value}")
+
+
+class DshMcpTransport:
+    _max_wire_response_bytes: int
+    _max_result_bytes: int
+
+    async def _mcp_request(
+        self,
+        lease: DshMcpConnectorLease,
+        *,
+        request_id: str,
+        method: Literal[
+            "initialize",
+            "io.ksadk/scopes/revoke",
+            "tools/list",
+            "tools/call",
+        ],
+        params: Mapping[str, Any],
+        timeout_seconds: float,
+    ) -> dict[str, Any]:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": method,
+            "params": dict(params),
+        }
+        headers = {**lease.headers(), "Content-Type": "application/json"}
+        try:
+            async with httpx.AsyncClient(
+                headers=headers,
+                timeout=timeout_seconds,
+                trust_env=False,
+            ) as client:
+                response = await client.post(lease.endpoint, json=payload)
+        except httpx.TimeoutException as error:
+            raise asyncio.TimeoutError from error
+        except httpx.HTTPError as error:
+            raise StudioError(
+                "DSH_CAPABILITY_HOST_UNAVAILABLE",
+                "DSH capability MCP 连接失败",
+                status_code=503,
+                details={"errorType": type(error).__name__},
+            ) from error
+        if response.status_code != 200 or len(response.content) > self._max_wire_response_bytes:
+            raise self._protocol_error()
+        try:
+            envelope = json.loads(
+                response.content,
+                object_pairs_hook=_duplicate_rejecting_object,
+                parse_constant=_reject_non_finite,
+            )
+        except (UnicodeError, ValueError, TypeError, RecursionError) as error:
+            raise self._protocol_error() from error
+        if (
+            not isinstance(envelope, dict)
+            or envelope.get("jsonrpc") != "2.0"
+            or envelope.get("id") != request_id
+        ):
+            raise self._protocol_error()
+        if "error" in envelope:
+            rpc_error = envelope.get("error")
+            code = rpc_error.get("code") if isinstance(rpc_error, dict) else None
+            raise StudioError(
+                "DSH_CAPABILITY_REQUEST_FAILED",
+                "DSH capability MCP 拒绝了请求",
+                status_code=502,
+                details={"rpcCode": code if isinstance(code, int) else None},
+            )
+        result = envelope.get("result")
+        if not isinstance(result, dict):
+            raise self._protocol_error()
+        try:
+            result_bytes = len(
+                json.dumps(
+                    result,
+                    allow_nan=False,
+                    ensure_ascii=False,
+                    separators=(",", ":"),
+                ).encode("utf-8")
+            )
+        except (TypeError, ValueError, RecursionError) as error:
+            raise self._protocol_error() from error
+        if result_bytes > self._max_result_bytes:
+            raise self._protocol_error()
+        return cast(dict[str, Any], result)
+
+    async def _initialize_lease(self, lease: DshMcpConnectorLease) -> None:
+        request_id = f"initialize-{os.urandom(12).hex()}"
+        result = await self._mcp_request(
+            lease,
+            request_id=request_id,
+            method="initialize",
+            params={
+                "protocolVersion": DSH_CAPABILITY_MCP_PROTOCOL,
+                "capabilities": {},
+                "clientInfo": {"name": "ksadk-studio", "version": "1.0.0"},
+            },
+            timeout_seconds=5.0,
+        )
+        server_info = result.get("serverInfo")
+        capabilities = result.get("capabilities")
+        if (
+            result.get("protocolVersion") != DSH_CAPABILITY_MCP_PROTOCOL
+            or not isinstance(server_info, dict)
+            or server_info.get("name") != DSH_CAPABILITY_BUNDLE_PACKAGE
+            or server_info.get("version") != DSH_CAPABILITY_HOST_VERSION
+            or not isinstance(capabilities, dict)
+            or not isinstance(capabilities.get("tools"), dict)
+        ):
+            raise self._protocol_error()
+        await self._send_notification(
+            lease,
+            method="notifications/initialized",
+            params={},
+            tolerate_failure=False,
+        )
+
+    async def _send_cancel(self, lease: DshMcpConnectorLease, call_id: str) -> None:
+        await self._send_notification(
+            lease,
+            method="notifications/cancelled",
+            params={"requestId": call_id, "reason": "Studio UI cancelled the call"},
+            tolerate_failure=True,
+        )
+
+    async def _send_notification(
+        self,
+        lease: DshMcpConnectorLease,
+        *,
+        method: Literal["notifications/initialized", "notifications/cancelled"],
+        params: Mapping[str, Any],
+        tolerate_failure: bool,
+    ) -> None:
+        headers = {**lease.headers(), "Content-Type": "application/json"}
+        payload = {"jsonrpc": "2.0", "method": method, "params": dict(params)}
+        try:
+            async with httpx.AsyncClient(headers=headers, timeout=2.0, trust_env=False) as client:
+                response = await client.post(lease.endpoint, json=payload)
+            if response.status_code not in {200, 202, 204}:
+                raise self._protocol_error()
+        except (httpx.HTTPError, StudioError):
+            # Disposal still kills the process and aborts all work.  Cancellation
+            # is best effort here so refresh/close cannot be held hostage by a
+            # broken loopback listener.
+            if tolerate_failure:
+                return
+            raise self._protocol_error() from None
+
+    @staticmethod
+    def _protocol_error() -> StudioError:
+        return StudioError(
+            "DSH_CAPABILITY_PROTOCOL_INVALID",
+            "DSH capability MCP 返回了无效响应",
+            status_code=502,
+        )

ksadk/studio/dsh_provider_registration.py

@@ -28,6 +28,7 @@ from ksadk.plugins.bridges.dsh import (
     DshProfileProjection,
 )
 from ksadk.plugins.contracts import CompositionProfile, PluginManifest
+from ksadk.plugins.dsh_home import default_studio_dsh_home, prepare_studio_dsh_home, studio_dsh_home
 from ksadk.plugins.dsh_toolchain import DSH_CORE_PACKAGES, DshToolchainManager
 from ksadk.plugins.host import ManagedPlugin, PluginHostError
 from ksadk.plugins.providers.codex_dsh import (
@@ -252,12 +253,7 @@ class StudioDshProviderRegistrationManager:
     def discover(cls, workspace: Path) -> "StudioDshProviderRegistrationManager | None":
         """Discover an initialized managed Profile without downloading tools."""
 
-        configured_home = os.environ.get("KSADK_DSH_HOME", "").strip()
-        home = (
-            Path(configured_home).expanduser()
-            if configured_home
-            else workspace / ".agentkit" / "dsh-home"
-        )
+        home = studio_dsh_home(workspace)
         profile = os.environ.get("KSADK_DSH_PROFILE", "").strip() or "web"
         configured_bin = os.environ.get("KSADK_DSH_BIN", "").strip()
         manifest = home / "profiles" / profile / "package.json"
@@ -282,7 +278,7 @@ class StudioDshProviderRegistrationManager:
         """Discover DSH or prepare the isolated first-run Studio Profile.
 
         The default is deliberately narrower than :meth:`discover`: only the
-        Studio-owned ``.agentkit/dsh-home`` and official ``web`` Profile qualify for
+        Studio-owned versioned home and official ``web`` Profile qualify for
         automatic official-provider bootstrap.  Explicit DSH homes/profiles
         are user-owned and are never mutated by Studio startup.
         """
@@ -292,7 +288,7 @@ class StudioDshProviderRegistrationManager:
         if configured_home or configured_profile:
             return cls.discover(workspace)
         root = workspace.resolve()
-        home = root / ".agentkit" / "dsh-home"
+        home = default_studio_dsh_home(root)
         configured_bin = os.environ.get("KSADK_DSH_BIN", "").strip()
         if configured_bin:
             command: Sequence[str] | None = (str(Path(configured_bin).expanduser()),)
@@ -326,7 +322,7 @@ class StudioDshProviderRegistrationManager:
                 return None
         return cls(
             root,
-            dsh_home=root / ".agentkit" / "dsh-home",
+            dsh_home=default_studio_dsh_home(root),
             profile="agentkit-resources",
             dsh_command=command,
         )
@@ -339,7 +335,7 @@ class StudioDshProviderRegistrationManager:
     def _owns_workspace_default_profile(self) -> bool:
         configured_home = os.environ.get("KSADK_DSH_HOME", "").strip()
         configured_profile = os.environ.get("KSADK_DSH_PROFILE", "").strip()
-        expected_home = (self._workspace / ".agentkit" / "dsh-home").resolve()
+        expected_home = default_studio_dsh_home(self._workspace)
         return (
             not configured_home
             and not configured_profile
@@ -369,6 +365,7 @@ class StudioDshProviderRegistrationManager:
 
         if not self._owns_workspace_default_profile:
             return "skipped"
+        prepare_studio_dsh_home(self._dsh_home)
         marker = self._default_marker_path
         marker_payload = self._read_default_marker(marker)
         command = self._dsh_command or DshToolchainManager().require_command()
@@ -419,6 +416,48 @@ class StudioDshProviderRegistrationManager:
             )
         return result
 
+    async def bootstrap_official_harness_provider(
+        self,
+    ) -> Literal["installed", "already_enabled", "disabled", "skipped"]:
+        """Install and preflight the wheel-owned Harness provider in the managed profile."""
+        if not self._owns_workspace_default_profile:
+            return "skipped"
+        async with self._lock:
+            return await asyncio.to_thread(self._bootstrap_official_harness_provider_sync)
+
+    def _bootstrap_official_harness_provider_sync(
+        self,
+    ) -> Literal["installed", "already_enabled", "disabled", "skipped"]:
+        if not self._owns_workspace_default_profile:
+            return "skipped"
+        prepare_studio_dsh_home(self._dsh_home)
+        command = self._dsh_command or DshToolchainManager().require_command()
+        shipped = shipped_harness_dsh_bundle()
+        with self._bridge_factory(
+            dsh_home=self._dsh_home, profile=self._profile,
+            dsh_command=command, cwd=self._workspace,
+        ) as bridge:
+            self._repair_owned_profile_layout(bridge)
+            installed = {item.name: item for item in bridge.list_plugins()}
+            current = installed.get(SHIPPED_HARNESS_DSH_PACKAGE)
+            if current is None:
+                current = bridge.install_plugin(str(shipped.root), accept_host_permissions=True)
+                result = "installed"
+            else:
+                result = "already_enabled" if current.enabled else "disabled"
+            if (current.name != SHIPPED_HARNESS_DSH_PACKAGE
+                    or current.version != SHIPPED_HARNESS_PROVIDER_VERSION):
+                raise StudioDshProviderRegistrationError(
+                    "harness_dsh_bundle_not_active",
+                    "the official Harness DSH Bundle version is not supported",
+                )
+            if result == "installed" and not current.enabled:
+                current = bridge.set_enabled(SHIPPED_HARNESS_DSH_PACKAGE, enabled=True)
+            if not current.enabled:
+                return "disabled"
+            self._verify_shipped_bundle_bytes(SHIPPED_HARNESS_DSH_PACKAGE)
+        return result
+
     async def bootstrap_official_resource_plugins(
         self,
     ) -> Literal["installed", "already_enabled", "disabled", "skipped"]:
@@ -434,6 +473,7 @@ class StudioDshProviderRegistrationManager:
     ) -> Literal["installed", "already_enabled", "disabled", "skipped"]:
         if not self._owns_workspace_default_profile:
             return "skipped"
+        prepare_studio_dsh_home(self._dsh_home)
         marker = self._default_marker_path
         marker_payload = self._read_default_marker(marker)
         command = self._dsh_command or DshToolchainManager().require_command()
@@ -581,12 +621,10 @@ class StudioDshProviderRegistrationManager:
 
     @property
     def _default_marker_path(self) -> Path:
-        # Scope the bootstrap receipt to the owned Profile.  Older Studio
-        # builds used one workspace-wide marker while their default Profile
-        # was ``studio``.  Reusing that marker after the default moved to
-        # official Core's ``web`` Profile incorrectly skipped first-run
-        # installation and left Studio with no runnable DSH Profile.
-        return self._workspace / ".agentkit" / f"official-dsh-defaults-{self._profile}.json"
+        # An old Core home's "already installed" receipt cannot suppress
+        # installation in a fresh version-isolated home. Keep explicit
+        # uninstall/disable decisions local to their actual Profile and Core.
+        return self._dsh_home / f"official-dsh-defaults-{self._profile}.json"
 
     @staticmethod
     def _read_default_marker(path: Path) -> dict[str, object]:
@@ -711,6 +749,7 @@ class StudioDshProviderRegistrationManager:
             )
 
     def _discover_profile(self) -> _ProfileSnapshot:
+        prepare_studio_dsh_home(self._dsh_home)
         command = self._dsh_command or DshToolchainManager().require_command()
         with self._bridge_factory(
             dsh_home=self._dsh_home,

ksadk/studio/entry.py

@@ -0,0 +1,53 @@
+"""Studio entry selection and local-session bootstrap responses."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Any
+
+from fastapi import Request
+from fastapi.responses import RedirectResponse, Response
+
+from ksadk.studio.errors import StudioError
+
+
+async def studio_entry_response(
+    studio: Any, request: Request, static_root: Path,
+) -> Response:
+    # Workspace navigation is contributed by the official Core client.
+    # Opening the standalone React shell with enabled plugins silently
+    # hides those pages. Select the host from Profile metadata, without
+    # starting Core just to decide which entry to serve.
+    use_core = False
+    if request.url.path == "/" and os.environ.get("KSADK_STUDIO_LAZY_START") != "1":
+        try:
+            # 有界等待：探测可能触发 Node bridge 冷启动（可达数十秒），
+            # 超时则先回 React shell，避免首屏长时间白屏；
+            # 预热完成后真实 Core 用户下次导航仍会拿到正确重定向。
+            use_core = await asyncio.wait_for(
+                studio.dsh_capabilities.has_enabled_profile_plugins(), timeout=2.0
+            )
+        except (asyncio.TimeoutError, StudioError, OSError, RuntimeError):
+            # The optional toolchain may be absent in a plain SDK workspace.
+            pass
+    if request.url.path == "/studio-recovery/":
+        from ksadk.studio.recovery_page import RECOVERY_HTML
+
+        response = Response(content=RECOVERY_HTML, media_type="text/html")
+    # Desktop startup keeps the shell available while Core starts.
+    elif use_core and os.environ.get("KSADK_STUDIO_LAZY_START") != "1":
+        target = "/studio-core/"
+        if request.url.query:
+            target += "?" + request.url.query
+        # Browsers inherit the original fragment across this redirect,
+        # preserving Agent/session/group deep links and CLI bootstrap.
+        response = RedirectResponse(target, status_code=307)
+    else:
+        path = static_root / "index.html"
+        html = path.read_text(encoding="utf-8")
+        # Keep hashed module URLs identical to internal lazy imports.
+        response = Response(content=html, media_type="text/html")
+    response.headers["Cache-Control"] = "no-store"
+    return response

ksadk/studio/event_store.py

@@ -20,6 +20,11 @@ class RunEventStore:
     def __init__(self, workspace: Workspace) -> None:
         self.workspace = workspace
         self.trace_store = OtlpTraceStore(workspace)
+        # (mtime, size, inode) → 已解析 (record, events)。流式期间 SSE 投影
+        # 每 50ms 调 events()/list_runs()，全量 JSON 解析 + Pydantic 验证会
+        # 随事件数线性放大（实测把事件循环拖到整段卡死）。同进程内写读方
+        # 在 _write/_read 之间共享此缓存；外部改动通过 stat 元数据失效。
+        self._cache: dict[str, tuple[tuple[float, int, int], tuple[Any, list[RunEvent]]]] = {}
 
     def _path(self, run_id: str) -> Path:
         return self.workspace.resolve(Path(".agentkit/runs") / f"{run_id}.json")
@@ -66,6 +71,23 @@ class RunEventStore:
             self._write(record, events)
         return appended
 
+    def append_record_events(
+        self, record: RunRecord, entries: list[tuple[str, dict[str, Any]]],
+    ) -> list[RunEvent]:
+        """Publish facts and their explicit Run state in the same file replace.
+
+        The caller's updated record need not be the object in the read cache.
+        There is no intermediate terminal record without its public fact.
+        """
+        _, events = self._read(record.id)
+        appended = [
+            RunEvent(id=len(events) + offset, run_id=record.id, type=kind, data=data)
+            for offset, (kind, data) in enumerate(entries, 1)
+        ]
+        if appended:
+            self._write(record, [*events, *appended])
+        return appended
+
     def append_interaction_resolution(
         self,
         run_id: str,
@@ -120,9 +142,13 @@ class RunEventStore:
         directory = self.workspace.resolve(".agentkit/runs")
         for path in sorted(directory.glob("run_*.json")):
             try:
-                payload = json.loads(path.read_text(encoding="utf-8"))
-                record = RunRecord.model_validate(payload["record"])
-            except (OSError, ValueError, KeyError, ValidationError):
+                # ``list_runs`` is polled while a chat is running.  Parsing every
+                # growing run file on every poll turns a streamed response into
+                # an O(polls * events) JSON workload and can consume an entire
+                # CPU core.  Route the read through the stat-aware cache used by
+                # ``get``/``events``; external edits still invalidate it.
+                record, _events = self._read(path.stem)
+            except (OSError, ValueError, KeyError, ValidationError, StudioError):
                 continue
             if session_id and record.session_id != session_id:
                 continue
@@ -146,6 +172,7 @@ class RunEventStore:
             if path.is_file():
                 self.trace_store.delete(record.trace_id, purge=True)
                 path.unlink()
+                self._cache.pop(record.id, None)
                 deleted += 1
         return deleted
 
@@ -231,15 +258,31 @@ class RunEventStore:
             status=status,
         )
 
+    @staticmethod
+    def _stat_key(path: Path) -> tuple[float, int, int]:
+        info = path.stat()
+        return (info.st_mtime, info.st_size, info.st_ino)
+
     def _read(self, run_id: str) -> tuple[RunRecord, list[RunEvent]]:
         path = self._path(run_id)
         if not path.is_file():
+            self._cache.pop(run_id, None)
             raise not_found("run", run_id)
+        try:
+            key = self._stat_key(path)
+        except OSError:
+            key = None
+        cached = self._cache.get(run_id)
+        if cached is not None and key is not None and cached[0] == key:
+            return cached[1]
         try:
             payload = json.loads(path.read_text(encoding="utf-8"))
             record = RunRecord.model_validate(payload["record"])
             events = [RunEvent.model_validate(item) for item in payload.get("events", [])]
-            return record, events
+            parsed = (record, events)
+            if key is not None:
+                self._cache[run_id] = (key, parsed)
+            return parsed
         except (OSError, ValueError, KeyError, ValidationError) as exc:
             raise StudioError(
                 "RUN_RECORD_INVALID",
@@ -256,7 +299,12 @@ class RunEventStore:
             payload["events"] = [
                 event.model_dump(by_alias=True, exclude_none=True, mode="json") for event in events
             ]
+        path = self._path(record.id)
         self.workspace.atomic_write_text(
-            self._path(record.id),
+            path,
             json.dumps(payload, ensure_ascii=False, sort_keys=True, indent=2) + "\n",
         )
+        try:
+            self._cache[record.id] = (self._stat_key(path), (record, list(events or [])))
+        except OSError:
+            self._cache.pop(record.id, None)