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

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/attachment_store.py

@@ -44,6 +44,13 @@ _TEXT_SUFFIXES = {
     ".yaml",
     ".yml",
 }
+_DOCUMENT_MEDIA_TYPES = {
+    "application/pdf",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+}
+_DOCUMENT_SUFFIXES = {".pdf", ".docx", ".pptx", ".xlsx"}
 
 
 @dataclass(frozen=True)
@@ -57,7 +64,7 @@ class StoredConversationAttachment:
 
 
 class ConversationAttachmentStore:
-    """Persist only the small image/text inputs supported by local Studio."""
+    """Persist bounded uploads; each Runtime separately admits its supported view."""
 
     MAX_BYTES = 1_500_000
 
@@ -88,7 +95,7 @@ class ConversationAttachmentStore:
         if not self._supported(content, filename=safe_name, media_type=normalized_type):
             raise StudioError(
                 "CONVERSATION_ATTACHMENT_TYPE_UNSUPPORTED",
-                "会话附件仅支持图片或 UTF-8 文本、代码文件",
+                "会话附件支持图片、UTF-8 文本、代码及 PDF、DOCX、PPTX、XLSX 文档",
                 status_code=415,
                 field="file",
             )
@@ -171,6 +178,11 @@ class ConversationAttachmentStore:
     def _supported(content: bytes, *, filename: str, media_type: str) -> bool:
         if media_type.startswith("image/"):
             return True
+        if (
+            media_type in _DOCUMENT_MEDIA_TYPES
+            or Path(filename).suffix.lower() in _DOCUMENT_SUFFIXES
+        ):
+            return True
         if (
             media_type.startswith("text/")
             or media_type in _TEXT_MEDIA_TYPES

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/build_resolution.py

@@ -0,0 +1,117 @@
+"""Resolve immutable Studio Builds shared by Web and Scheduler admission."""
+
+import asyncio
+import json
+import zipfile
+
+from ksadk.studio.a2a_bindings import bindings_digest
+from ksadk.studio.contracts import BuildStatus
+from ksadk.studio.errors import StudioError
+from ksadk.studio.resource_build_admission import resource_build_required
+
+
+def _locked_definition_matches(studio, record, expected_digest: str) -> bool:
+    if not record.artifact_path:
+        return False
+    try:
+        path = studio.workspace.resolve(record.artifact_path, must_exist=True)
+        with zipfile.ZipFile(path) as archive:
+            lock = json.loads(archive.read("agentkit.lock"))
+        return isinstance(lock, dict) and lock.get("definitionDigest") == expected_digest
+    except (OSError, ValueError, KeyError, zipfile.BadZipFile):
+        return False
+
+
+async def resolve_current_build(studio, agent_id: str):
+    """Return the Build that is eligible for a local Studio turn.
+
+    This is deliberately one shared resolver for Web chat and Scheduler
+    authoring.  A Scheduler must never select a mutable Draft or a stale
+    Codex manifest merely because a UI happened to show it as an Agent.
+    """
+
+    await studio.start()
+    if studio.is_codex_agent(agent_id):
+        studio.codex_agent_detail(agent_id)
+        manifest_snapshot = studio.codex_manifests.load(agent_id)
+        await studio.a2a_catalog.validate_bindings(manifest_snapshot.manifest.remote_agents or [])
+        cached = studio._current_codex_builds.get(agent_id)
+        if cached is not None and cached.manifest_sha256 == manifest_snapshot.manifest_sha256:
+            try:
+                return studio.codex_builds.get(cached.id)
+            except StudioError:
+                studio._current_codex_builds.pop(agent_id, None)
+        builds = [
+            record
+            for record in studio.codex_builds.list()
+            if record.agent_name == agent_id and studio.codex_builder.is_current(record)
+        ]
+        if builds:
+            studio._current_codex_builds[agent_id] = builds[0]
+            return builds[0]
+        built = await asyncio.to_thread(studio.codex_builder.build, agent_id)
+        studio._current_codex_builds[agent_id] = built
+        return built
+    draft = studio.drafts.get(agent_id)
+    await studio.a2a_catalog.validate_bindings(draft.spec.bindings.remote_agents)
+    from ksadk.studio.a2a_orchestration import compile_orchestration
+
+    a2a_composition = compile_orchestration(draft)
+    a2a_composition_digest = a2a_composition.digest if a2a_composition else None
+    composition_required = studio.plugin_compositions.required_for(draft)
+    resources_required = resource_build_required(draft)
+    # SDK catalog definitions can change without a Draft revision (e.g. a
+    # corrected builtin argument schema). Keep each existing Build immutable,
+    # but select a fresh Build for new turns when a bound definition changed.
+    # Agents without builtin bindings keep their existing admission path.
+    builtin_bindings = any(
+        binding.enabled and binding.resource_id.startswith("tool:builtin:")
+        for binding in draft.spec.bindings.tools
+    )
+    current_definition_digest = None
+    for record in studio.builds.list_for_agent(agent_id):
+        if record.status == BuildStatus.SUCCEEDED:
+            if record.a2a_orchestration_digest != a2a_composition_digest:
+                continue
+            if record.a2a_binding_digest != bindings_digest(draft.spec.bindings.remote_agents):
+                continue
+            # Every runtime type is revision-bound.  Framework Builds are
+            # just as immutable as composed Harness Builds and must never
+            # be reused after the Agent draft revision changes.
+            if record.source_revision != draft.metadata.revision:
+                continue
+            if composition_required and not studio._build_has_composition(record):
+                continue
+            if resources_required and not studio._build_has_resources(record):
+                continue
+            if builtin_bindings:
+                if current_definition_digest is None:
+                    compiled = await asyncio.to_thread(studio.builder.compiler.compile, draft)
+                    current_definition_digest = compiled.resolved.resolved_digest
+                if not _locked_definition_matches(studio, record, current_definition_digest):
+                    continue
+            if composition_required:
+                composition = studio.plugin_compositions.compile_if_required(draft)
+                if composition is None:  # pragma: no cover - guarded by required_for
+                    raise StudioError(
+                        "PLUGIN_COMPOSITION_REQUIRED",
+                        "当前 Agent 需要插件组合，但无法生成 Composition",
+                        status_code=409,
+                    )
+                if not studio._build_has_composition(record, composition=composition):
+                    continue
+                studio.plugin_compositions.bind_build(
+                    composition,
+                    agent_id=draft.metadata.id,
+                    build_id=record.id,
+                )
+            return record
+    if draft.spec.model is None and not draft.spec.bindings.model_profile_id:
+        raise StudioError(
+            "AGENT_MODEL_REQUIRED",
+            "当前 Agent 未绑定 Model Profile，请先在 Agent 配置中选择模型；"
+            "API Key 只提供访问凭证，不会自动绑定模型。",
+            status_code=422,
+            field="spec.bindings.modelProfileId",
+        )
+    return await asyncio.to_thread(studio._build_agent_bundle, draft)

ksadk/studio/build_singleflight.py

@@ -0,0 +1,37 @@
+"""Join in-flight builds; cancellation of one UI request does not own the build."""
+
+import asyncio
+from collections.abc import Awaitable, Callable, Hashable
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+class BuildSingleFlight:
+    def __init__(self):
+        self.pending: dict[tuple[str, Hashable | None], asyncio.Task[Any]] = {}
+
+    async def run(
+        self, agent_id: str, build: Callable[[], Awaitable[T]], *,
+        identity: Callable[[], Hashable] | None = None,
+    ) -> T:
+        while True:
+            revision = identity() if identity is not None else None
+            key = (agent_id, revision)
+            task = self.pending.get(key)
+            if task is None:
+                task = asyncio.create_task(build())
+                self.pending[key] = task
+
+                def settled(completed, owned_key=key):
+                    if self.pending.get(owned_key) is completed:
+                        self.pending.pop(owned_key, None)
+                    if not completed.cancelled():
+                        completed.exception()  # Observe failures after all UI waiters detach.
+
+                task.add_done_callback(settled)
+            result = await asyncio.shield(task)
+            # Saving during prewarm does not authorize a later turn to execute
+            # that older revision. Other waiters still own the old task.
+            if identity is None or identity() == revision:
+                return result

ksadk/studio/builder.py

@@ -142,6 +142,27 @@ class AgentBundleBuilder:
         resource_reference = None
         try:
             self._copy_runtime_source(bundle_root, draft)
+            for filename, content in (("studio_a2a_composition.py", compiled.a2a_source),
+                                      ("studio_a2a_entry.py", compiled.a2a_entry_source)):
+                if content is None:
+                    continue
+                generated = bundle_root / "runtime" / filename
+                if generated.exists():
+                    raise ValueError("A2A_GENERATED_SOURCE_CONFLICT")
+                generated.parent.mkdir(parents=True, exist_ok=True)
+                generated.write_text(content, encoding="utf-8")
+            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(
@@ -253,7 +274,11 @@ class AgentBundleBuilder:
             shutil.rmtree(staging, ignore_errors=True)
 
         now = datetime.now(timezone.utc)
+        from ksadk.studio.a2a_bindings import bindings_digest
+
         record = BuildRecord(
+            a2a_binding_digest=bindings_digest(compiled.resolved.remote_agents),
+            a2a_orchestration_digest=(compiled.resolved.a2a_orchestration or {}).get("digest"),
             id=build_id,
             agent_id=draft.metadata.id,
             source_revision=draft.metadata.revision,
@@ -444,6 +469,11 @@ class AgentBundleBuilder:
             "model": compiled.resolved.model.model,
             "models": list(dict.fromkeys(bound_models)),
         }
+        if compiled.a2a_source is not None:
+            lock["originalEntryPoint"] = lock["entryPoint"]
+            lock["originalAgentVariable"] = lock["agentVariable"]
+            lock["entryPoint"] = "studio_a2a_entry.py"
+            lock["agentVariable"] = "root_agent"
         return (
             runtime_type,
             source_digest,
@@ -479,8 +509,8 @@ class AgentBundleBuilder:
             {
                 "name": draft.metadata.id,
                 "framework": runtime.type,
-                "entry_point": runtime.entry_point or "agent.py",
-                "agent_variable": runtime.agent_variable or "root_agent",
+                "entry_point": "studio_a2a_entry.py" if draft.spec.a2a_orchestration else (runtime.entry_point or "agent.py"),
+                "agent_variable": "root_agent" if draft.spec.a2a_orchestration else (runtime.agent_variable or "root_agent"),
                 "package": ".",
             },
         )