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

ksadk/studio/api_contracts.py

@@ -30,6 +30,12 @@ class WorkspaceOpenRequest(ContractModel):
     create: bool = False
 
 
+class LinkedDirectoryRequest(ContractModel):
+    path: str
+    mode: Literal["read", "write"] = "read"
+    label: str | None = Field(default=None, max_length=128)
+
+
 class CreateAgentRequest(ContractModel):
     id: str = Field(pattern=r"^[a-z][a-z0-9-]{2,62}$")
     name: str = Field(min_length=1, max_length=128)
@@ -80,7 +86,7 @@ class MessageInput(ContractModel):
 class QuickAuthoringRequest(ContractModel):
     name: str = Field(min_length=1, max_length=128)
     slug: str | None = Field(default=None, min_length=1, max_length=63)
-    runtime_type: Literal["codex", "adk", "langgraph", "plugin"]
+    runtime_type: Literal["harness", "codex", "adk", "langgraph", "plugin"]
     template: Literal["blank", "research"] = "blank"
     description: str = Field(default="", max_length=1024)
     spec: AgentSpec | None = None
@@ -100,7 +106,7 @@ class ConversationAuthoringRequest(ContractModel):
     # Runtime is a Studio-owned deployment choice.  The authoring model only
     # supplies semantic intent and must not choose an incompatible framework
     # source contract on its own.
-    runtime_type: Literal["codex", "adk", "langgraph"] = "codex"
+    runtime_type: Literal["harness", "codex", "adk", "langgraph"] = "codex"
     agent_model_profile_ids: list[str] = Field(default_factory=list, max_length=100)
     agent_default_model_profile_id: str | None = Field(
         default=None,

ksadk/studio/api_plugin_routes.py

@@ -38,6 +38,12 @@ from ksadk.plugins.codex_manifest import (
     CodexPluginSourceCoordinate,
     snapshot_installed_codex_plugin,
 )
+from ksadk.plugins.dsh_home import (
+    DshHomeVersionError,
+    dsh_home_diagnostic,
+    prepare_studio_dsh_home,
+    studio_dsh_home,
+)
 from ksadk.plugins.dsh_toolchain import DshToolchainError, DshToolchainManager
 from ksadk.plugins.host import PluginHostError
 from ksadk.studio.codex_plugin_store import (
@@ -98,13 +104,14 @@ def _studio_codex_home(studio: StudioService) -> tuple[Path, str]:
     return studio.workspace.root / ".agentkit" / "codex-home", "workspace-isolated"
 
 
+def _active_studio(studio):
+    """Resolve the active runtime while retaining compatibility with direct test fixtures."""
+    return getattr(studio, "active", studio)
+
+
 def _studio_dsh_options(studio: StudioService) -> tuple[Path, str, tuple[str, ...] | None, str]:
     configured_home = os.environ.get("KSADK_DSH_HOME", "").strip()
-    home = (
-        Path(configured_home).expanduser()
-        if configured_home
-        else studio.workspace.root / ".agentkit" / "dsh-home"
-    )
+    home = studio_dsh_home(studio.workspace.root)
     configured_bin = os.environ.get("KSADK_DSH_BIN", "").strip()
     if configured_bin:
         command = (str(Path(configured_bin).expanduser()),)
@@ -513,6 +520,11 @@ def _codex_error(error: Exception) -> StudioError:
 
 
 def _dsh_error(error: Exception) -> StudioError:
+    if isinstance(error, DshHomeVersionError):
+        return StudioError(
+            "DSH_HOME_VERSION_UNVERIFIED", str(error), status_code=409,
+            details=error.diagnostic,
+        )
     if isinstance(error, DshPluginNotFoundError):
         return StudioError("DSH_PLUGIN_NOT_FOUND", "DSH 插件未安装", status_code=404)
     if isinstance(error, DshPluginApprovalRequired):
@@ -539,10 +551,8 @@ def _dsh_error(error: Exception) -> StudioError:
 def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
     """Register only DSH Profile and Codex App Server lifecycle routes."""
 
-    codex_home, codex_mode = _studio_codex_home(studio)
-    dsh_home, dsh_profile, dsh_command, dsh_mode = _studio_dsh_options(studio)
-
     def public_dsh(item: DshPluginInventory, host: DshBridgeHost) -> dict[str, Any]:
+        _, _, _, dsh_mode = _studio_dsh_options(_active_studio(studio))
         return _public_dsh_inventory(
             item,
             host=host,
@@ -550,8 +560,14 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
             runtime_state=studio.dsh_provider_runtime_state(item.name),
         )
 
-    def call_dsh(operation: Callable[[DshProfilePluginBridge], Any]) -> Any:
+    def call_dsh(operation: Callable[[DshProfilePluginBridge], Any], *, write: bool = False) -> Any:
+        dsh_home, dsh_profile, dsh_command, _ = _studio_dsh_options(_active_studio(studio))
         try:
+            # Even a read-only bridge creates its synchronization directory.
+            # Fence an empty home first so that lockfile cannot make our own
+            # fresh home look like an unversioned legacy installation later.
+            if write or dsh_home_diagnostic(dsh_home)["status"] == "new":
+                prepare_studio_dsh_home(dsh_home)
             with DshProfilePluginBridge(
                 dsh_home=dsh_home, profile=dsh_profile, dsh_command=dsh_command
             ) as bridge:
@@ -591,6 +607,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
     async def list_codex_plugins(
         installed_only: bool = Query(default=False), force_refetch: bool = Query(default=False)
     ):
+        codex_home, codex_mode = _studio_codex_home(_active_studio(studio))
         try:
             async with CodexAppServerPluginBridge(codex_home=codex_home) as bridge:
                 items = await bridge.list_plugins(force_refetch=force_refetch)
@@ -620,6 +637,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
     async def get_codex_plugin(
         plugin_id: str, marketplace_name: str | None = Query(default=None, max_length=256)
     ):
+        codex_home, codex_mode = _studio_codex_home(_active_studio(studio))
         try:
             async with CodexAppServerPluginBridge(codex_home=codex_home) as bridge:
                 detail = await bridge.read_plugin(plugin_id, marketplace_name=marketplace_name)
@@ -635,6 +653,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
 
     @app.post("/api/v1/plugin-ecosystems/codex/plugins/{plugin_id}:snapshot")
     async def snapshot_codex_plugin(plugin_id: str, payload: CodexPluginSnapshotRequest):
+        codex_home, codex_mode = _studio_codex_home(_active_studio(studio))
         """Explicitly admit already-installed host bytes into the workspace store."""
 
         try:
@@ -661,6 +680,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
 
     @app.post("/api/v1/plugin-ecosystems/codex/plugins/{plugin_id}:install")
     async def install_codex_plugin(plugin_id: str, payload: CodexPluginInstallRequest):
+        codex_home, codex_mode = _studio_codex_home(_active_studio(studio))
         if not payload.accept_undeclared_permissions:
             raise _codex_error(CodexPluginApprovalRequired("approval required"))
         try:
@@ -745,6 +765,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
 
     @app.delete("/api/v1/plugin-ecosystems/codex/plugins/{plugin_id}", status_code=204)
     async def uninstall_codex_plugin(plugin_id: str):
+        codex_home, codex_mode = _studio_codex_home(_active_studio(studio))
         try:
             async with CodexAppServerPluginBridge(codex_home=codex_home) as bridge:
                 await bridge.uninstall_plugin(plugin_id)
@@ -754,6 +775,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
 
     @app.get("/api/v1/plugin-ecosystems/dsh/plugins")
     async def list_dsh_plugins():
+        dsh_home, dsh_profile, _, dsh_mode = _studio_dsh_options(_active_studio(studio))
         try:
             host, items = await asyncio.to_thread(call_dsh, lambda bridge: bridge.list_plugins())
             return {
@@ -762,6 +784,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
                 "profile": dsh_profile,
                 "host": _public_host("dsh", host, home_mode=dsh_mode),
                 "items": [public_dsh(item, host) for item in items],
+                "homeCompatibility": dsh_home_diagnostic(dsh_home, workspace=studio.workspace.root),
             }
         except StudioError as error:
             return {
@@ -771,12 +794,14 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
                 "host": _public_host("dsh", None, home_mode=dsh_mode),
                 "items": [],
                 "error": {"code": error.code, "message": error.message},
+                "homeCompatibility": dsh_home_diagnostic(dsh_home, workspace=studio.workspace.root),
             }
 
     @app.get("/api/v1/plugin-ecosystems/dsh/profile")
     async def get_dsh_profile_projection():
+        _, dsh_profile, _, dsh_mode = _studio_dsh_options(_active_studio(studio))
         host, projection = await asyncio.to_thread(
-            call_dsh, lambda bridge: bridge.project_profile()
+            call_dsh, lambda bridge: bridge.project_profile(), write=True,
         )
         return {
             "host": _public_host("dsh", host, home_mode=dsh_mode),
@@ -812,7 +837,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
         async def operation():
             # Do not release Studio's admission fence while a cancelled HTTP
             # request still has a filesystem migration running in its thread.
-            task = asyncio.create_task(asyncio.to_thread(call_dsh, migrate))
+            task = asyncio.create_task(asyncio.to_thread(call_dsh, migrate, write=True))
             cancelled = False
             while not task.done():
                 try:
@@ -844,6 +869,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
             return await asyncio.to_thread(
                 call_dsh,
                 lambda bridge: bridge.install_plugin(payload.source, accept_host_permissions=True),
+                write=True,
             )
 
         host, item = await studio.reconfigure_dsh_profile(install)
@@ -863,7 +889,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
             return await asyncio.to_thread(call_dsh, action)
 
         async def mutate():  # type: ignore[no-untyped-def]
-            return await asyncio.to_thread(call_dsh, action)
+            return await asyncio.to_thread(call_dsh, action, write=True)
 
         return await studio.reconfigure_dsh_profile(mutate)
 
@@ -886,6 +912,7 @@ def register_plugin_routes(app: FastAPI, studio: StudioService) -> None:
             return await asyncio.to_thread(
                 call_dsh,
                 lambda bridge: bridge.update_plugin(plugin_name, accept_host_permissions=True),
+                write=True,
             )
 
         host, item = await studio.reconfigure_dsh_profile(update)

ksadk/studio/api_resource_connections.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import asyncio
-import os
 from pathlib import Path
 from typing import Any, Literal
 
@@ -43,6 +42,63 @@ class ValidateResourceBindings(PluginContractModel):
     expected_revision: int = Field(strict=True, ge=1)
 
 
+async def _bootstrap_default_connection(studio: Any) -> dict[str, Any] | None:
+    """Lazily provision the local declaration from configured credentials."""
+    authority = getattr(studio, "resource_authority", None)
+    configuration = getattr(studio, "configuration", None)
+    environment = configuration.environment() if configuration is not None else {}
+    access_key = environment.get("KSYUN_ACCESS_KEY", "").strip()
+    secret_key = environment.get("KSYUN_SECRET_KEY", "").strip()
+    if authority is None or not access_key or not secret_key:
+        return None
+    connection_ref = "ksyun-platform-default"
+    try:
+        existing = await asyncio.to_thread(studio.resource_connections.get, connection_ref)
+    except StudioError as error:
+        if error.status_code != 404:
+            raise
+    else:
+        return {**existing.model_dump(by_alias=True, mode="json"), "validationState": "verified"}
+    tenant_ref, principal_ref = await asyncio.to_thread(
+        authority.resolve_signed_identity, access_key, secret_key
+    )
+    declaration = ResourceConnectionDeclaration(
+        label="金山云平台资源",
+        target=ConnectionTarget(
+            connection_ref=connection_ref,
+            tenant_ref=tenant_ref,
+            principal_ref=principal_ref,
+            endpoint=authority.policy.allowed_data_endpoints[0],
+            auth_mode="signed",
+        ),
+        credentials=ResourceCredentialReferences(
+            access_key_ref="env://KSYUN_ACCESS_KEY",
+            secret_key_ref="env://KSYUN_SECRET_KEY",
+        ),
+    )
+    try:
+        record = await asyncio.to_thread(
+            studio.resource_connections.save, declaration, expected_revision=0
+        )
+    except StudioError as error:
+        if error.status_code != 409:
+            raise
+        record = await asyncio.to_thread(studio.resource_connections.get, connection_ref)
+    return {**record.model_dump(by_alias=True, mode="json"), "validationState": "verified"}
+
+
+def _binding_region(kind: PlatformResourceKind, service_region: str, control_region: str) -> str:
+    """Memory's Default-CN is a service label, not an API signing region.
+
+    Resolve only this known service label at discovery, using the signed
+    client's region. Persist the resulting binding normally; never broaden the
+    host allowlist or silently rewrite an existing Revision/Bundle.
+    """
+    if kind == "memory-instance" and service_region == "Default-CN":
+        return control_region
+    return service_region
+
+
 def register_resource_connection_routes(app: FastAPI, studio: Any) -> None:
     @app.get("/api/v1/platform-resources")
     async def list_platform_resources(kind: PlatformResourceKind):
@@ -68,6 +124,9 @@ def register_resource_connection_routes(app: FastAPI, studio: Any) -> None:
             / plugin_id.split(".", 1)[1]
         )
         connections = await asyncio.to_thread(studio.resource_connections.list)
+        if not connections:
+            await _bootstrap_default_connection(studio)
+            connections = await asyncio.to_thread(studio.resource_connections.list)
         connection_ref = connections[0].target.connection_ref if connections else None
         return {
             "kind": kind,
@@ -79,7 +138,8 @@ def register_resource_connection_routes(app: FastAPI, studio: Any) -> None:
                 {
                     "id": str(item.get("id") or ""),
                     "name": str(item.get("name") or item.get("id") or ""),
-                    "region": str(item.get("region") or ""),
+                    "region": _binding_region(kind, str(item.get("region") or ""), client.region),
+                    "serviceRegion": str(item.get("region") or ""),
                     "status": str(item.get("status") or "unknown"),
                     "disabled": bool(item.get("disabled", False)),
                     "disableReason": str(item.get("disable_reason") or ""),
@@ -97,50 +157,28 @@ def register_resource_connection_routes(app: FastAPI, studio: Any) -> None:
 
     @app.post("/api/v1/resource-connections:bootstrap", status_code=201)
     async def bootstrap_resource_connection():
-        authority = studio.resource_authority
-        access_key = os.environ.get("KSYUN_ACCESS_KEY", "").strip()
-        secret_key = os.environ.get("KSYUN_SECRET_KEY", "").strip()
+        authority = getattr(studio, "resource_authority", None)
+        # Resolve through Studio's configuration precedence (workspace,
+        # global config, inherited environment, dotenv), rather than only the
+        # process environment. This keeps discovery and connection bootstrap
+        # on the same credential source.
+        environment = studio.configuration.environment()
+        access_key = environment.get("KSYUN_ACCESS_KEY", "").strip()
+        secret_key = environment.get("KSYUN_SECRET_KEY", "").strip()
         if authority is None or not access_key or not secret_key:
             raise StudioError(
                 "RESOURCE_CONNECTION_BOOTSTRAP_UNAVAILABLE",
-                "请先通过 Studio env-file 配置云端签名凭证和控制面地址",
+                "请先在设置的云端连接中填写账号凭据和控制面地址",
                 status_code=503,
             )
-        tenant_ref, principal_ref = await asyncio.to_thread(
-            authority.resolve_signed_identity, access_key, secret_key
-        )
-        connection_ref = "ksyun-platform-default"
-        try:
-            existing = await asyncio.to_thread(studio.resource_connections.get, connection_ref)
-        except StudioError as error:
-            if error.status_code != 404:
-                raise
-        else:
-            return {
-                **existing.model_dump(by_alias=True, mode="json"),
-                "validationState": "verified",
-            }
-        declaration = ResourceConnectionDeclaration(
-            label="金山云平台资源",
-            target=ConnectionTarget(
-                connection_ref=connection_ref,
-                tenant_ref=tenant_ref,
-                principal_ref=principal_ref,
-                endpoint=authority.policy.allowed_data_endpoints[0],
-                auth_mode="signed",
-            ),
-            credentials=ResourceCredentialReferences(
-                access_key_ref="env://KSYUN_ACCESS_KEY",
-                secret_key_ref="env://KSYUN_SECRET_KEY",
-            ),
-        )
-        record = await asyncio.to_thread(
-            studio.resource_connections.save, declaration, expected_revision=0
-        )
-        return {
-            **record.model_dump(by_alias=True, mode="json"),
-            "validationState": "verified",
-        }
+        result = await _bootstrap_default_connection(studio)
+        if result is None:
+            raise StudioError(
+                "RESOURCE_CONNECTION_BOOTSTRAP_UNAVAILABLE",
+                "请先在设置的云端连接中填写账号凭据和控制面地址",
+                status_code=503,
+            )
+        return result
 
     @app.get("/api/v1/agents/{agent_id}/resource-bindings/status")
     async def binding_status(

ksadk/studio/authoring.py

@@ -40,7 +40,7 @@ from ksadk.studio.workspace import Workspace
 _SLUG = re.compile(r"[^a-z0-9]+")
 _MAX_IMPORT_BYTES = 100 * 1024 * 1024
 _MAX_IMPORT_FILES = 2000
-_SUPPORTED_RUNTIMES = frozenset({"codex", "adk", "langgraph"})
+_SUPPORTED_RUNTIMES = frozenset({"harness", "codex", "adk", "langgraph"})
 
 
 class ConversationProposal(BaseModel):
@@ -48,7 +48,7 @@ class ConversationProposal(BaseModel):
 
     name: str = Field(min_length=1, max_length=128)
     slug: str = Field(min_length=1, max_length=63)
-    runtimeType: Literal["codex", "adk", "langgraph"]
+    runtimeType: Literal["harness", "codex", "adk", "langgraph"]
     description: str = Field(default="", max_length=1024)
     spec: AgentSpec
 
@@ -128,18 +128,24 @@ class AgentAuthoringService:
         if normalized not in _SUPPORTED_RUNTIMES:
             raise StudioError(
                 "RUNTIME_NOT_SUPPORTED",
-                "创建方式仅支持 Codex、ADK 和 LangGraph",
+                "创建方式仅支持 KsADK Harness、Codex、ADK 和 LangGraph",
                 status_code=422,
                 field="runtimeType",
                 details={"runtimeType": normalized},
             )
-        if normalized == "codex":
+        if normalized in {"codex", "harness"}:
             # A new YAML Agent must lock the CLI actually installed on this
             # Studio host. Cloud admission resolves that explicit version via
             # the Server-owned catalog instead of accepting a client image.
+            from ksadk.version import VERSION
+
             return RuntimeRef(
-                type="codex",
-                version=installed_runtime_version("codex") or "0.144.4",
+                type=cast(Any, normalized),
+                version=(
+                    installed_runtime_version("codex") or "0.154.0"
+                    if normalized == "codex"
+                    else VERSION
+                ),
             )
         return RuntimeRef(
             type=cast(Any, normalized),

ksadk/studio/authoring_coordinator.py

@@ -28,7 +28,7 @@ from ksadk.studio.contracts import (
 )
 from ksadk.studio.errors import StudioError
 from ksadk.studio.identifiers import generate_agent_slug, is_generated_agent_slug
-from ksadk.studio.templates import default_agent_spec
+from ksadk.studio.templates import default_agent_spec, with_harness_provider_permissions
 
 LOGGER = logging.getLogger(__name__)
 
@@ -319,6 +319,8 @@ class StudioAuthoringCoordinator:
                     canonical_runtime.version = proposed_runtime.version
                     canonical_runtime.detection = proposed_runtime.detection
             resolved.runtime = canonical_runtime
+            if runtime_type == "harness" and spec is None:
+                resolved = with_harness_provider_permissions(resolved)
             if _uses_codex_native_tools(canonical_runtime):
                 resolved.bindings = resolved.bindings.model_copy(update={"tools": []})
                 resolved.capabilities = resolved.capabilities.model_copy(update={"tools": []})
@@ -609,7 +611,7 @@ class StudioAuthoringCoordinator:
             getattr(model, "endpoint_url", "-"),
         )
         normalized_runtime_type = str(runtime_type or "").strip().lower()
-        if normalized_runtime_type not in {"codex", "adk", "langgraph"}:
+        if normalized_runtime_type not in {"harness", "codex", "adk", "langgraph"}:
             raise StudioError(
                 "AGENT_RUNTIME_INVALID",
                 "对话构建 Runtime 仅支持 Codex、ADK 或 LangGraph",

ksadk/studio/builder.py

@@ -142,6 +142,18 @@ class AgentBundleBuilder:
         resource_reference = None
         try:
             self._copy_runtime_source(bundle_root, draft)
+            if draft.spec.runtime and draft.spec.runtime.type == "harness":
+                from ksadk.plugins.providers.harness_tools import python_tool_bundle_path
+
+                for tool in compiled.resolved.capabilities.tools:
+                    if tool.enabled and tool.executor == "python":
+                        source = self.workspace.resolve(tool.source_path, must_exist=True)
+                        content = source.read_bytes()
+                        if "sha256:" + hashlib.sha256(content).hexdigest() != tool.source_sha256:
+                            raise ValueError("Python Tool source changed since registration")
+                        target = bundle_root / python_tool_bundle_path(tool.source_sha256)
+                        target.parent.mkdir(parents=True, exist_ok=True)
+                        target.write_bytes(content)
             self._write_runtime_launch_config(bundle_root, draft)
             if resource_build is not None:
                 resource_reference = resource_build.materialize(

ksadk/studio/capabilities.py

@@ -150,12 +150,29 @@ class LocalCapabilityResolver:
         payload.pop("digest", None)
         digest = sha256_digest(canonical_json(payload))
         if contract.digest and contract.digest != digest:
-            raise StudioError(
-                "CAPABILITY_DIGEST_MISMATCH",
-                "Tool 合同与声明 digest 不一致",
-                status_code=422,
-                details={"name": contract.name, "expected": contract.digest, "actual": digest},
-            )
+            # 运行时生成的内置工具没有持久化源头，合同随宿主状态（后端可用
+            # 性、插件注册）重算；compose 与 build 之间的状态漂移会误报失配，
+            # 这里按当前目录重算放行。已发布/持久化工具仍严格拒改。
+            from ksadk.toolsets import describe_agentengine_tools
+
+            runtime_names = {
+                str(item.get("name"))
+                for item in describe_agentengine_tools(profile="coding", mode="direct")
+            }
+            # 目录/合同用连字符命名，运行时注册名是下划线：两种变体都认。
+            normalized = {name.replace("_", "-") for name in runtime_names}
+            normalized |= runtime_names
+            if contract.name not in normalized:
+                raise StudioError(
+                    "CAPABILITY_DIGEST_MISMATCH",
+                    "Tool 合同与声明 digest 不一致",
+                    status_code=422,
+                    details={
+                        "name": contract.name,
+                        "expected": contract.digest,
+                        "actual": digest,
+                    },
+                )
         return cast(
             ToolContract,
             contract.model_copy(update={"digest": digest}),