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

ksadk/plugins/dsh_toolchain.py

@@ -8,6 +8,7 @@ an ordinary npm package that follows DSH's public ``dsh.bundle.patch`` format.
 
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import re
@@ -32,11 +33,27 @@ from ksadk.plugins.bridges.dsh import (
 )
 
 DSH_PACKAGE = "@deepseek-ai/dsh"
-DSH_VERSION = "0.1.1-rc.2"
+DSH_VERSION = "0.1.5-rc.1"
 DSH_PACKAGE_SPEC = f"{DSH_PACKAGE}@{DSH_VERSION}"
-CORDIS_VERSION_RANGE = "^4.0.1"
+DSH_GITHUB_TAG = "dsh-v0.1.5-rc.1"
+DSH_GITHUB_COMMIT = "183f08e9c6dde7e36cd2318eaee70b0da08fb35e"
+CORDIS_VERSION_RANGE = "^4.0.2"
 PNPM_VERSION = "11.7.0"
 
+# The managed package is a complete Core DSH distribution.  Keep these
+# packages explicit so a registry/dist-tag mistake cannot silently degrade the
+# installation into the old capability-only mini host.
+DSH_CORE_PACKAGES = (
+    "@deepseek-ai/dsh-base",
+    "@deepseek-ai/dsh-web-app",
+    "@deepseek-ai/dsh-cordis-client-runner",
+    "@deepseek-ai/dsh-client-ui-cordis",
+    "@deepseek-ai/dsh-app-boot",
+    "@deepseek-ai/dsh-headless",
+    "@deepseek-ai/dsh-sdk-app",
+    "@deepseek-ai/dsh-mcp-client",
+)
+
 TOOLCHAIN_HOME_ENV = "AGENTENGINE_PLUGIN_TOOLCHAIN_HOME"
 PNPM_BIN_ENV = "AGENTENGINE_PNPM_BIN"
 
@@ -49,6 +66,38 @@ _STALE_LOCK_SECONDS = 10 * 60
 _MAX_MANIFEST_BYTES = 2 * 1024 * 1024
 
 
+def _dependency_policy() -> str:
+    """Keep the official synchronized DSH packages on the reviewed release.
+
+    The published CLI uses caret dependencies even for release candidates.
+    Pinning only the CLI would allow its Core/client packages to resolve to a
+    later candidate. The pnpm hook changes resolution, not upstream source.
+    """
+
+    return (
+        "// Generated by KsADK; the complete DSH release is an atomic dependency.\n"
+        f"const version = {json.dumps(DSH_VERSION)};\n"
+        "module.exports = { hooks: { readPackage(pkg) {\n"
+        "  for (const field of ['dependencies', 'optionalDependencies', 'peerDependencies']) {\n"
+        "    for (const name of Object.keys(pkg[field] || {})) {\n"
+        "      if (name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-')) {\n"
+        "        const requested = pkg[field][name];\n"
+        "        if (!/^[~^<>=*xX0-9][0-9A-Za-z.*+~^<>=| -]*$/.test(requested)) {\n"
+        "          throw new Error('DSH dependencies require a release version: ' + name);\n"
+        "        }\n"
+        "        if (/^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$/.test(requested)\n"
+        "            && requested !== version) {\n"
+        "          throw new Error('DSH dependency version conflicts with host: ' + name);\n"
+        "        }\n"
+        "        pkg[field][name] = version;\n"
+        "      }\n"
+        "    }\n"
+        "  }\n"
+        "  return pkg;\n"
+        "} } };\n"
+    )
+
+
 def _to_camel(value: str) -> str:
     head, *tail = value.split("_")
     return head + "".join(part.capitalize() for part in tail)
@@ -65,7 +114,7 @@ class _ToolchainModel(BaseModel):
 
 class DshToolchainStatus(_ToolchainModel):
     package: Literal["@deepseek-ai/dsh"] = DSH_PACKAGE
-    expected_version: Literal["0.1.1-rc.2"] = DSH_VERSION
+    expected_version: Literal["0.1.5-rc.1"] = DSH_VERSION
     installed: bool
     usable: bool
     root: str
@@ -128,9 +177,16 @@ class DshPluginSourceError(DshToolchainError):
 
 
 class DshPluginValidationError(DshToolchainError):
-    def __init__(self, stage: str, message: str = "DSH plugin validation failed") -> None:
+    def __init__(
+        self,
+        stage: str,
+        message: str = "DSH plugin validation failed",
+        *,
+        diagnostic: str | None = None,
+    ) -> None:
         super().__init__(message)
         self.stage = stage
+        self.diagnostic = diagnostic
 
 
 class DshPluginPackError(DshToolchainError):
@@ -244,6 +300,26 @@ class DshToolchainManager:
                 actual_version=actual,
                 problem="version_mismatch",
             )
+        if not self._core_package_graph_is_complete():
+            return self._status(
+                installed=True,
+                usable=False,
+                pnpm_path=pnpm_path,
+                pnpm_version=pnpm_version,
+                executable=str(executable),
+                actual_version=actual,
+                problem="core_packages_missing_or_mismatched",
+            )
+        if not self._receipt_is_valid():
+            return self._status(
+                installed=True,
+                usable=False,
+                pnpm_path=pnpm_path,
+                pnpm_version=pnpm_version,
+                executable=str(executable),
+                actual_version=actual,
+                problem="receipt_missing_or_mismatched",
+            )
         return self._status(
             installed=True,
             usable=True,
@@ -307,6 +383,10 @@ class DshToolchainManager:
                     raise DshToolchainVersionMismatchError(
                         f"expected DSH {DSH_VERSION}, got {actual}"
                     )
+                if not self._core_package_graph_is_complete(staging):
+                    raise DshToolchainInstallError(
+                        "installed DSH package does not contain the pinned Core runtime graph"
+                    )
                 self._write_receipt(staging, actual)
                 if self._root.exists():
                     backup = parent / f".{DSH_VERSION}.backup-{uuid.uuid4().hex}"
@@ -342,7 +422,9 @@ class DshToolchainManager:
 
         if explicit is not None and str(explicit).strip():
             executable = self._resolve_program(str(explicit))
-            actual = self._command_version((executable,), cwd=self._root)
+            # An explicit installation does not require the managed default root
+            # to exist (for example in a fresh Studio HOME).
+            actual = self._command_version((executable,), cwd=Path(executable).parent)
             if actual != DSH_VERSION:
                 raise DshToolchainVersionMismatchError(
                     f"expected DSH {DSH_VERSION}, got {actual}"
@@ -405,11 +487,22 @@ class DshToolchainManager:
 
     def require_pnpm(self) -> tuple[str, ...]:
         command = self._resolve_pnpm_command()
-        result = self._runner(
-            (*command, "--version"),
-            self._pnpm_probe_cwd(),
-            self._pnpm_environment(),
-        )
+        if self._root.exists():
+            result = self._runner(
+                (*command, "--version"),
+                self._root,
+                self._pnpm_environment(),
+            )
+        else:
+            # pnpm walks parent directories looking for packageManager.  A
+            # first install under a home directory must not inherit an
+            # unrelated Yarn/npm project from one of those parents.
+            with tempfile.TemporaryDirectory(prefix="ksadk-pnpm-probe-") as directory:
+                result = self._runner(
+                    (*command, "--version"),
+                    Path(directory),
+                    self._pnpm_environment(),
+                )
         match = _VERSION.search(result.stdout or result.stderr)
         if match is None:
             raise DshToolchainUnavailableError("pnpm did not report a parseable version")
@@ -472,27 +565,23 @@ class DshToolchainManager:
         executable = self._resolve_program(command[0])
         return (executable, *command[1:])
 
-    def _pnpm_probe_cwd(self) -> Path:
-        # require_pnpm() must also work before the managed toolchain root
-        # exists (first install), so the version probe cannot unconditionally
-        # use self._root as cwd.
-        if self._root.exists():
-            return self._root
-        self._base_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
-        return self._base_dir
-
     def _manifest_is_pinned(self, path: Path | None = None) -> bool:
         manifest_path = path or self._root / "package.json"
         try:
             payload = json.loads(manifest_path.read_text(encoding="utf-8"))
         except (FileNotFoundError, OSError, UnicodeError, json.JSONDecodeError):
             return False
+        try:
+            policy = (manifest_path.parent / ".pnpmfile.cjs").read_text(encoding="utf-8")
+        except (OSError, UnicodeError):
+            return False
         return (
             isinstance(payload, dict)
             and payload.get("private") is True
             and payload.get("packageManager") == f"pnpm@{PNPM_VERSION}"
             and isinstance(payload.get("dependencies"), dict)
             and payload["dependencies"].get(DSH_PACKAGE) == DSH_VERSION
+            and policy == _dependency_policy()
         )
 
     def _lockfile_is_pinned(self, path: Path | None = None) -> bool:
@@ -503,7 +592,61 @@ class DshToolchainManager:
             value = lockfile.read_text(encoding="utf-8")
         except (FileNotFoundError, OSError, UnicodeError):
             return False
-        return DSH_PACKAGE in value and DSH_VERSION in value
+        # Package and snapshot keys include peer suffixes. Match the package's
+        # own version before the suffix rather than a dependency mentioned in it.
+        packages = re.findall(
+            r"^  ['\"]?(@deepseek-ai/dsh(?:-[a-z0-9-]+)?)@([^('\":\s]+)",
+            value,
+            re.MULTILINE,
+        )
+        return (DSH_PACKAGE, DSH_VERSION) in packages and all(
+            version == DSH_VERSION for _name, version in packages
+        )
+
+    def _core_package_graph_is_complete(self, root: Path | None = None) -> bool:
+        install_root = root or self._root
+        dsh_manifest = install_root / "node_modules" / DSH_PACKAGE / "package.json"
+        try:
+            resolved_manifest = dsh_manifest.resolve(strict=True)
+            payload = json.loads(resolved_manifest.read_text(encoding="utf-8"))
+        except (FileNotFoundError, OSError, UnicodeError, json.JSONDecodeError):
+            return False
+        dependencies = payload.get("dependencies") if isinstance(payload, dict) else None
+        if not isinstance(dependencies, dict):
+            return False
+        for package in DSH_CORE_PACKAGES:
+            requirement = dependencies.get(package)
+            # pnpm keeps transitive dependencies beside the real dsh package
+            # inside its virtual store, not necessarily at the project root.
+            manifest = (
+                resolved_manifest.parent.parent.parent
+                / Path(*package.split("/"))
+                / "package.json"
+            )
+            if (
+                not isinstance(requirement, str)
+                or DSH_VERSION not in requirement
+                or not manifest.is_file()
+            ):
+                return False
+            try:
+                installed = json.loads(manifest.read_text(encoding="utf-8"))
+            except (OSError, UnicodeError, json.JSONDecodeError):
+                return False
+            if (
+                not isinstance(installed, dict)
+                or installed.get("name") != package
+                or installed.get("version") != DSH_VERSION
+            ):
+                return False
+        return True
+
+    def _receipt_is_valid(self) -> bool:
+        try:
+            receipt = json.loads((self._root / "toolchain.json").read_text(encoding="utf-8"))
+            return receipt == self._receipt(self._root, DSH_VERSION)
+        except (OSError, UnicodeError, json.JSONDecodeError):
+            return False
 
     def _command_version(self, command: Sequence[str], *, cwd: Path) -> str:
         result = self._invoke((*command, "--version"), cwd=cwd)
@@ -547,18 +690,30 @@ class DshToolchainManager:
                 "dependencies": {DSH_PACKAGE: DSH_VERSION},
             },
         )
+        (root / ".pnpmfile.cjs").write_text(_dependency_policy(), encoding="utf-8")
 
     def _write_receipt(self, root: Path, actual: str) -> None:
-        self._write_json(
-            root / "toolchain.json",
-            {
-                "schemaVersion": 1,
-                "package": DSH_PACKAGE,
-                "requestedVersion": DSH_VERSION,
-                "actualVersion": actual,
-                "packageManager": f"pnpm@{PNPM_VERSION}",
-            },
-        )
+        self._write_json(root / "toolchain.json", self._receipt(root, actual))
+
+    @staticmethod
+    def _receipt(root: Path, actual: str) -> dict[str, Any]:
+        return {
+            "schemaVersion": 2,
+            "package": DSH_PACKAGE,
+            "requestedVersion": DSH_VERSION,
+            "actualVersion": actual,
+            "githubTag": DSH_GITHUB_TAG,
+            "githubCommit": DSH_GITHUB_COMMIT,
+            "distribution": "core",
+            "corePackages": list(DSH_CORE_PACKAGES),
+            "packageManager": f"pnpm@{PNPM_VERSION}",
+            "lockDigest": "sha256:" + hashlib.sha256(
+                (root / "pnpm-lock.yaml").read_bytes()
+            ).hexdigest(),
+            "dependencyPolicyDigest": "sha256:" + hashlib.sha256(
+                (root / ".pnpmfile.cjs").read_bytes()
+            ).hexdigest(),
+        }
 
     @staticmethod
     def _write_json(path: Path, value: object) -> None:
@@ -791,10 +946,23 @@ class DshPluginDeveloper:
                     )
             except DshToolchainError:
                 raise
+            except ValueError as error:
+                if stage == "install":
+                    raise DshPluginSourceError(str(error)) from error
+                raise DshPluginValidationError(
+                    stage,
+                    diagnostic=_redact_diagnostic(str(error)),
+                ) from error
             except DshBridgeError as error:
-                raise DshPluginValidationError(stage) from error
+                raise DshPluginValidationError(
+                    stage,
+                    diagnostic=_redact_diagnostic(str(error)),
+                ) from error
             except Exception as error:
-                raise DshPluginValidationError(stage) from error
+                raise DshPluginValidationError(
+                    stage,
+                    diagnostic=_redact_diagnostic(str(error)),
+                ) from error
 
     def pack(
         self,
@@ -902,6 +1070,9 @@ class DshPluginDeveloper:
 
 __all__ = [
     "CORDIS_VERSION_RANGE",
+    "DSH_CORE_PACKAGES",
+    "DSH_GITHUB_COMMIT",
+    "DSH_GITHUB_TAG",
     "DSH_PACKAGE",
     "DSH_PACKAGE_SPEC",
     "DSH_VERSION",

ksadk/plugins/ecosystem_probe.py

@@ -13,6 +13,7 @@ import json
 from pathlib import Path
 from typing import Any
 
+from ksadk.plugins.codex_manifest import CodexPluginManifestError, load_codex_plugin_manifest
 from ksadk.plugins.ecosystem_bridge import (
     BridgeProbeExchange,
     BridgeProbeRequest,
@@ -111,9 +112,10 @@ def probe_ecosystem_manifests(
     codex_path = root / ".codex-plugin" / "plugin.json"
     if codex_path.exists():
         raw = _read_manifest(codex_path, root=root)
-        payload = _json_object(raw, name=".codex-plugin/plugin.json")
-        if not isinstance(payload.get("name"), str) or not payload["name"]:
-            raise EcosystemProbeError("Codex plugin manifest requires a non-empty name")
+        try:
+            load_codex_plugin_manifest(root)
+        except CodexPluginManifestError as exc:
+            raise EcosystemProbeError(str(exc)) from exc
         candidates.append(
             _candidate(
                 ecosystem="codex",
@@ -176,9 +178,7 @@ def probe_ecosystem_manifests(
             raise EcosystemProbeError("selected manifest was not detected in the source directory")
         selection_required = len(candidates) > 1 and selected_manifest_ref is None
         selected = (
-            None
-            if selection_required
-            else selected_manifest_ref or candidates[0].manifest_ref
+            None if selection_required else selected_manifest_ref or candidates[0].manifest_ref
         )
         result = BridgeProbeResult(
             candidates=tuple(candidates),

ksadk/plugins/execution_host.py

@@ -0,0 +1,99 @@
+"""Versioned, provider-neutral execution ports granted to trusted plugins.
+
+The host resolves bindings and authorizes every operation. Implementations must
+not accept a model/browser-supplied PluginExecutionScope as authorization.
+No collaboration or scheduling policy belongs to this contract.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+EXECUTION_HOST_PROTOCOL = "ksadk.execution-host/v1"
+
+
+@dataclass(frozen=True)
+class PluginExecutionScope:
+    plugin_id: str
+    plugin_digest: str
+    authority_ref: str
+    tenant_id: str
+    owner_subject: str
+    binding_ref: str
+    session_id: str
+
+
+@dataclass(frozen=True)
+class ExecutionReceipt:
+    status: Literal["missing", "accepted", "duplicate", "rejected", "uncertain"]
+    command_id: str | None = None
+    message_id: str | None = None
+    run_id: str | None = None
+    run_status: str | None = None
+    reason: str | None = None
+    output: str = ""
+    tokens: int = 0
+    source_event_id: str | None = None
+
+
+@dataclass(frozen=True)
+class ExecutionBarrier:
+    state: Literal["active", "suspended", "revoked"]
+    revision: int
+    in_flight: tuple[str, ...] = ()
+    queued: tuple[str, ...] = ()
+    discarded: tuple[str, ...] = ()
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+class PluginExecutionHost(Protocol):
+    async def describe(self, scope: PluginExecutionScope) -> dict[str, Any]: ...
+
+    async def ensure_session(self, scope: PluginExecutionScope) -> None: ...
+
+    async def submit(
+        self,
+        scope: PluginExecutionScope,
+        *,
+        content: str,
+        idempotency_key: str,
+        grant_id: str,
+        causation: str,
+        policy_context: dict[str, Any],
+    ) -> ExecutionReceipt: ...
+
+    async def lookup(
+        self, scope: PluginExecutionScope, idempotency_key: str
+    ) -> ExecutionReceipt: ...
+
+    async def set_grant(
+        self,
+        scope: PluginExecutionScope,
+        grant_id: str,
+        state: Literal["active", "suspended", "revoked"],
+        idempotency_key: str,
+    ) -> ExecutionBarrier: ...
+
+    async def cancel(
+        self, scope: PluginExecutionScope, run_id: str, idempotency_key: str
+    ) -> ExecutionReceipt: ...
+
+    async def interactions(self, scope: PluginExecutionScope) -> list[dict[str, Any]]: ...
+
+    async def get_interaction(
+        self, scope: PluginExecutionScope, *, run_id: str, interaction_id: str
+    ) -> dict[str, Any] | None: ...
+
+    async def submit_interaction(
+        self,
+        scope: PluginExecutionScope,
+        *,
+        run_id: str,
+        interaction_id: str,
+        expected_revision: int,
+        action: str,
+        response: dict[str, Any],
+        idempotency_key: str,
+        actor_subject: str,
+    ) -> dict[str, Any]: ...