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

ksadk/plugins/dsh_dependency_policy.py

@@ -0,0 +1,41 @@
+"""Render the reviewed pnpm dependency-resolution policy without host effects."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+
+
+def dependency_policy(version: str, vendor_versions: Mapping[str, str]) -> 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(version)};\n"
+        f"const vendorVersions = {json.dumps(vendor_versions, sort_keys=True)};\n"
+        "module.exports = { hooks: { readPackage(pkg) {\n"
+        "  for (const field of ['dependencies', 'optionalDependencies', 'peerDependencies']) {\n"
+        "    for (const name of Object.keys(pkg[field] || {})) {\n"
+        "      const target = name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-')\n"
+        "        ? version : vendorVersions[name];\n"
+        "      if (target !== undefined) {\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 !== target) {\n"
+        "          throw new Error('DSH dependency version conflicts with host: ' + name);\n"
+        "        }\n"
+        "        pkg[field][name] = target;\n"
+        "      }\n"
+        "    }\n"
+        "  }\n"
+        "  return pkg;\n"
+        "} } };\n"
+    )

ksadk/plugins/dsh_home.py

@@ -0,0 +1,140 @@
+"""Version-fenced Studio DSH homes; never upgrade an existing session store in place."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from ksadk.plugins.dsh_toolchain import DSH_GITHUB_COMMIT, DSH_GITHUB_TAG, DSH_VERSION
+from ksadk.plugins.host import PluginHostError
+
+_RECEIPT = ".ksadk-dsh-home.json"
+_RECOVERY = (
+    "原 DSH 目录已保留。请使用原版本工具链和原目录恢复；"
+    "或取消 KSADK_DSH_HOME，使用 Studio 新版本隔离目录，"
+    "逐个重装经过验证的固定版本插件。不要把新版 Session 日志交给旧 Core。"
+)
+
+
+class DshHomeVersionError(PluginHostError):
+    def __init__(self, diagnostic: dict[str, Any]) -> None:
+        self.diagnostic = diagnostic
+        super().__init__("dsh_home_version_unverified", _RECOVERY)
+
+
+def default_studio_dsh_home(workspace: Path) -> Path:
+    return workspace.resolve() / ".agentkit" / "dsh-homes" / DSH_VERSION
+
+
+def studio_dsh_home(workspace: Path) -> Path:
+    """Resolve only; safe for read-only catalog routes and lazy construction."""
+    configured = os.environ.get("KSADK_DSH_HOME", "").strip()
+    return (
+        Path(configured).expanduser().resolve()
+        if configured
+        else default_studio_dsh_home(workspace)
+    )
+
+
+def _receipt() -> dict[str, Any]:
+    return {
+        "schemaVersion": 1,
+        "dshVersion": DSH_VERSION,
+        "releaseTag": DSH_GITHUB_TAG,
+        "sourceCommit": DSH_GITHUB_COMMIT,
+        "sessionMigration": "none",
+    }
+
+
+def dsh_home_diagnostic(home: Path, *, workspace: Path | None = None) -> dict[str, Any]:
+    """Return bounded compatibility facts without reading logs or exposing paths."""
+    result: dict[str, Any] = {
+        "expectedVersion": DSH_VERSION,
+        "status": "new",
+        "writeAllowed": True,
+        "reason": "empty_home",
+    }
+    if workspace is not None:
+        legacy = workspace.resolve() / ".agentkit" / "dsh-home"
+        result["legacyHomePreserved"] = legacy.is_dir() and legacy.resolve() != home.resolve()
+    if not home.exists():
+        return result
+    if not home.is_dir():
+        result.update(status="invalid", writeAllowed=False, reason="home_not_directory")
+    else:
+        receipt = home / _RECEIPT
+        if receipt.is_file() and not receipt.is_symlink():
+            try:
+                if receipt.stat().st_size > 4096:
+                    raise ValueError("oversize receipt")
+                payload = json.loads(receipt.read_text())
+            except (OSError, ValueError, UnicodeError):
+                result.update(status="invalid", writeAllowed=False, reason="receipt_invalid")
+            else:
+                if payload == _receipt():
+                    result.update(status="compatible", reason="receipt_matches")
+                    return result
+                result.update(status="mismatch", writeAllowed=False, reason="receipt_mismatch")
+                version = payload.get("dshVersion") if isinstance(payload, dict) else None
+                if isinstance(version, str) and re.fullmatch(
+                    r"[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]{1,40})?", version
+                ):
+                    result["observedVersion"] = version
+        elif any(home.iterdir()):
+            result.update(status="unverified", writeAllowed=False, reason="receipt_missing")
+    if not result["writeAllowed"]:
+        result["recovery"] = _RECOVERY
+    return result
+
+
+@contextmanager
+def _home_lock(home: Path):
+    home.parent.mkdir(parents=True, exist_ok=True)
+    lock = home.parent / f".{home.name}.ksadk-version.lock"
+    with lock.open("a+b") as stream:
+        try:
+            import fcntl
+        except ImportError:
+            import msvcrt
+
+            stream.write(b"0")
+            stream.flush()
+            stream.seek(0)
+            msvcrt.locking(stream.fileno(), msvcrt.LK_LOCK, 1)
+            try:
+                yield
+            finally:
+                stream.seek(0)
+                msvcrt.locking(stream.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            fcntl.flock(stream.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(stream.fileno(), fcntl.LOCK_UN)
+
+
+def prepare_studio_dsh_home(home: Path) -> None:
+    """Before a Core start or Profile mutation, fence a previously clean home."""
+    home = home.expanduser().resolve()
+    with _home_lock(home):
+        diagnostic = dsh_home_diagnostic(home)
+        if not diagnostic["writeAllowed"]:
+            raise DshHomeVersionError(diagnostic)
+        if diagnostic["status"] == "compatible":
+            return
+        home.mkdir(parents=True, exist_ok=True)
+        fd, temporary = tempfile.mkstemp(prefix=".home-receipt-", dir=home)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as stream:
+                json.dump(_receipt(), stream, sort_keys=True, separators=(",", ":"))
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, home / _RECEIPT)
+        finally:
+            Path(temporary).unlink(missing_ok=True)

ksadk/plugins/dsh_teams.py

@@ -0,0 +1,105 @@
+"""Wheel-owned Teams bundle graph installed by the official DSH Profile bridge."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from ksadk.plugins.bridges.dsh import DshProfilePluginBridge
+from ksadk.plugins.companions import DshCompanionDefinition
+from ksadk.plugins.dsh_home import prepare_studio_dsh_home
+
+TEAMS_PLUGIN_ID = "io.ksadk.teams"
+TEAMS_PLUGIN_VERSION = "0.1.0"
+TEAMS_COMPONENTS = {
+    f"dsh-teams-{part}": f"@kingsoftcloud/dsh-teams-{part}"
+    for part in ("profile", "tasks", "router", "tools", "leader-policy", "client")
+}
+TEAMS_OPERATIONS = frozenset(
+    {
+        "team_context",
+        "team_message",
+        "team_create_task",
+        "team_task_action",
+        "team_wait",
+        "team_submit_result",
+        "team_finish",
+        "team_publish_artifact",
+        "team_read_artifact",
+    }
+)
+
+
+def teams_companion_definition(application: Any) -> DshCompanionDefinition:
+    root = Path(__file__).parent
+    sources = (
+        *sorted((root / "teams").glob("*.py")),
+        root / "companions.py",
+        root / "companion_artifacts.py",
+        root / "dsh_teams.py",
+        root / "providers" / "dsh_capabilities.py",
+        root / "providers" / "bundles" / "ksadk-dsh-companion-host" / "index.mjs",
+        root / "providers" / "bundles" / "ksadk-dsh-companion-host" / "client.mjs",
+    )
+    return DshCompanionDefinition(
+        plugin_id=TEAMS_PLUGIN_ID,
+        components=TEAMS_COMPONENTS,
+        operations=TEAMS_OPERATIONS,
+        start=application.start,
+        revoke=application.revoke,
+        close=application.close,
+        invoke=application.invoke,
+        profile="web",
+        bind_artifact=getattr(application, "bind_artifact", None),
+        artifact_sources=sources,
+    )
+
+
+def configure_teams_profile(
+    *,
+    workspace: Path,
+    dsh_home: Path,
+    dsh_command: Sequence[str],
+    enabled: bool,
+) -> dict[str, Any]:
+    """Apply all six enabled flags atomically after the caller enters maintenance.
+
+    The existing bridge owns the Profile lock, immutable sources, validation,
+    pnpm graph and rollback. A single outer transaction covers the stack;
+    individual DSH operations remain the same validated operations as the UI.
+    Installation is explicit, and this function never opens a second Core.
+    """
+    prepare_studio_dsh_home(dsh_home)
+    with DshProfilePluginBridge(
+        dsh_home=dsh_home,
+        profile="web",
+        dsh_command=dsh_command,
+        cwd=workspace,
+    ) as bridge:
+        with bridge._profile_transaction(exclusive=True):
+            snapshot = bridge._snapshot()
+            try:
+                installed = {item.name: item for item in bridge.list_plugins()}
+                if enabled:
+                    for component, package in TEAMS_COMPONENTS.items():
+                        current = installed.get(package)
+                        if current is None:
+                            root = Path(__file__).parent / "providers" / "bundles" / component
+                            current = bridge.install_plugin(str(root), accept_host_permissions=True)
+                        if current.name != package or current.version != TEAMS_PLUGIN_VERSION:
+                            raise ValueError("unsupported Teams companion bundle")
+                        bridge.set_enabled(package, enabled=True)
+                else:
+                    for package in reversed(tuple(TEAMS_COMPONENTS.values())):
+                        if package in installed:
+                            bridge.set_enabled(package, enabled=False)
+                projection = bridge.project_profile()
+                return {
+                    "profile": "web",
+                    "enabled": enabled,
+                    "profileDigest": projection.config_digest,
+                }
+            except BaseException as error:
+                bridge._rollback(snapshot, error)
+                raise

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
@@ -30,15 +31,31 @@ from ksadk.plugins.bridges.dsh import (
     DshProfilePluginBridge,
     dsh_subprocess_environment,
 )
+from ksadk.plugins.dsh_dependency_policy import dependency_policy
 
 DSH_PACKAGE = "@deepseek-ai/dsh"
-DSH_VERSION = "0.1.2-rc.1"
+DSH_VERSION = "0.1.7-rc.1"
 DSH_PACKAGE_SPEC = f"{DSH_PACKAGE}@{DSH_VERSION}"
-DSH_GITHUB_TAG = "dsh-v0.1.2-rc.1"
-DSH_GITHUB_COMMIT = "a66e4702047846cdaa10c66c9d3df3951f5ea70d"
-CORDIS_VERSION_RANGE = "^4.0.2"
+DSH_GITHUB_TAG = "dsh-v0.1.7-rc.1"
+DSH_GITHUB_COMMIT = "46a7f68b0922371ce7144b668b90e377d8e799f4"
+CORDIS_VERSION_RANGE = "^4.0.4"
 PNPM_VERSION = "11.7.0"
 
+# Versions from vendor/*/package.json at DSH_GITHUB_COMMIT. The DSH release
+# requires their service APIs as well as the synchronized dsh-* packages;
+# Pin the matching tag's complete vendor graph, including schema APIs used by
+# the release's plugins. Pins from an older DSH release are not compatible.
+DSH_VENDOR_VERSIONS = {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/cordis-plugin-group": "1.0.4",
+    "@deepseek-ai/cordis-plugin-include": "1.0.9",
+    "@deepseek-ai/cordis-plugin-loader": "1.0.5",
+    "@deepseek-ai/cordis-plugin-hmr": "1.0.19",
+    "@deepseek-ai/cordis-plugin-timer": "1.1.6",
+    "@deepseek-ai/cosmokit": "1.8.5",
+    "@deepseek-ai/schemastery": "3.18.4",
+}
+
 # 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.
@@ -47,7 +64,7 @@ DSH_CORE_PACKAGES = (
     "@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-app-boot", "@deepseek-ai/dsh-hmr",
     "@deepseek-ai/dsh-headless",
     "@deepseek-ai/dsh-sdk-app",
     "@deepseek-ai/dsh-mcp-client",
@@ -65,6 +82,11 @@ _STALE_LOCK_SECONDS = 10 * 60
 _MAX_MANIFEST_BYTES = 2 * 1024 * 1024
 
 
+def _dependency_policy() -> str:
+    """Render the policy from the pinned versions owned by this module."""
+    return dependency_policy(DSH_VERSION, DSH_VENDOR_VERSIONS)
+
+
 def _to_camel(value: str) -> str:
     head, *tail = value.split("_")
     return head + "".join(part.capitalize() for part in tail)
@@ -81,7 +103,7 @@ class _ToolchainModel(BaseModel):
 
 class DshToolchainStatus(_ToolchainModel):
     package: Literal["@deepseek-ai/dsh"] = DSH_PACKAGE
-    expected_version: Literal["0.1.2-rc.1"] = DSH_VERSION
+    expected_version: Literal["0.1.7-rc.1"] = DSH_VERSION
     installed: bool
     usable: bool
     root: str
@@ -277,6 +299,16 @@ class DshToolchainManager:
                 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,
@@ -528,12 +560,17 @@ class DshToolchainManager:
             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:
@@ -544,7 +581,16 @@ 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
@@ -572,8 +618,25 @@ class DshToolchainManager:
                 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)
         match = _VERSION.search(result.stdout or result.stderr)
@@ -616,22 +679,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,
-                "githubTag": DSH_GITHUB_TAG,
-                "githubCommit": DSH_GITHUB_COMMIT,
-                "distribution": "core",
-                "corePackages": list(DSH_CORE_PACKAGES),
-                "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:

ksadk/plugins/execution_host.py

@@ -0,0 +1,107 @@
+"""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 set_admission(
+        self,
+        scope: PluginExecutionScope,
+        grant_id: str,
+        allowed: bool,
+        idempotency_key: str,
+    ) -> ExecutionBarrier: ...
+
+    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]: ...