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

ksadk/studio/builder.py

@@ -10,7 +10,14 @@ from datetime import datetime, timezone
 from pathlib import Path
 from uuid import uuid4
 
+from ksadk.plugins.bundle_security import assert_bundle_security
+from ksadk.plugins.contracts import CompositionProfile, PluginLock, plugin_lock_digest
+from ksadk.plugins.resolver import ResolvedComposition
 from ksadk.studio.capabilities import canonical_json, compute_bundle_digest, sha256_digest
+from ksadk.studio.compatibility_report import (
+    build_bundle_compatibility_report,
+    compatibility_facts_digest,
+)
 from ksadk.studio.compiler import AgentCompiler
 from ksadk.studio.contracts import (
     AgentDraft,
@@ -19,11 +26,17 @@ from ksadk.studio.contracts import (
     BundleManifest,
     FileEntry,
 )
+from ksadk.studio.errors import StudioError
 from ksadk.studio.hosted_kernel import (
     build_hosted_kernel_requirement,
     hosted_kernel_requirement_digest,
 )
 from ksadk.studio.repository import BuildRepository
+from ksadk.studio.resource_build_admission import (
+    AdmittedResourceBuild,
+    resource_build_required,
+)
+from ksadk.studio.soul import render_soul_markdown
 from ksadk.studio.workspace import Workspace
 
 _ZIP_TIMESTAMP = (1980, 1, 1, 0, 0, 0)
@@ -43,29 +56,77 @@ class AgentBundleBuilder:
         self.compiler = compiler or AgentCompiler(workspace)
         self.repository = repository or BuildRepository(workspace)
 
-    def build(self, draft: AgentDraft) -> BuildRecord:
+    def build(
+        self,
+        draft: AgentDraft,
+        *,
+        composition: ResolvedComposition | None = None,
+        resource_build: AdmittedResourceBuild | None = None,
+    ) -> BuildRecord:
         LOGGER.info(
             "bundle build started: agent=%s revision=%s",
             draft.metadata.id,
             draft.metadata.revision,
         )
+        requires_resource_build = resource_build_required(draft)
+        if requires_resource_build != (resource_build is not None):
+            raise StudioError(
+                "RESOURCE_BUILD_ADMISSION_REQUIRED",
+                "平台资源绑定必须通过可信准入后写入同一个 AgentBundle",
+                status_code=409,
+                field="spec.bindings.plugins",
+            )
         compiled = self.compiler.compile(draft)
-        # Bundle v2 always carries a lock. Phase 1 deliberately supports no
-        # user-selectable plugin factories yet, so the only valid lock is the
-        # explicit empty set. This makes admission deterministic without
-        # pulling the Phase 2 PluginHost into a deployed runtime.
-        plugin_lock = {"lockFormat": "agentkit.plugin-lock/v1", "plugins": []}
-        plugin_lock_digest = sha256_digest(canonical_json(plugin_lock))
-        runtime_type, source_digest, runtime_lock = self._runtime_snapshot(draft, compiled)
-        resolved_digest = sha256_digest(
-            canonical_json(
-                {
-                    "definitionDigest": compiled.resolved.resolved_digest,
-                    "runtime": runtime_lock,
-                    "sourceDigest": source_digest,
-                }
+        if composition is None and any(
+            server.get("materialization") == "dsh-profile"
+            for server in compiled.resolved.capabilities.mcp_servers
+        ):
+            raise StudioError(
+                "PLUGIN_COMPOSITION_REQUIRED",
+                "动态 DSH MCP 必须通过当前草稿的 Plugin composition 构建",
+                status_code=409,
+                field="spec.bindings.mcpServers",
             )
+        if composition is not None and (
+            not composition.source_digest
+            or composition.source_digest != compiled.resolved.source_digest
+        ):
+            raise StudioError(
+                "PLUGIN_COMPOSITION_SOURCE_MISMATCH",
+                "Plugin composition 与当前 Agent 草稿快照不一致，请重新编译",
+                status_code=409,
+                field="spec.bindings",
+            )
+        # Bundle v2 already carries a deterministic empty lock.  P2-00A now
+        # validates that wire shape through PluginLock while deliberately not
+        # resolving or loading a PluginHost before P2-02/P2-03.
+        parsed_plugin_lock = composition.plugin_lock if composition else PluginLock()
+        plugin_lock = parsed_plugin_lock.model_dump(
+            by_alias=True,
+            exclude_none=True,
+            mode="json",
         )
+        plugin_lock_digest_value = plugin_lock_digest(parsed_plugin_lock)
+        composition_profile = composition.profile if composition else None
+        composition_profile_digest_value = composition.profile_digest if composition else None
+        runtime_type, source_digest, runtime_lock = self._runtime_snapshot(draft, compiled)
+        compatibility_facts_digest_value = compatibility_facts_digest(
+            draft=draft,
+            composition=composition,
+            runtime_lock=runtime_lock,
+        )
+        resolved_digest_payload = {
+            "compatibilityFactsDigest": compatibility_facts_digest_value,
+            "definitionDigest": compiled.resolved.resolved_digest,
+            "runtime": runtime_lock,
+            "sourceDigest": source_digest,
+        }
+        if composition is not None:
+            resolved_digest_payload["compositionProfileDigest"] = composition_profile_digest_value
+            resolved_digest_payload["pluginLockDigest"] = plugin_lock_digest_value
+        if resource_build is not None:
+            resolved_digest_payload["resourceSnapshotDigest"] = resource_build.snapshot.digest
+        resolved_digest = sha256_digest(canonical_json(resolved_digest_payload))
         short_digest = resolved_digest.removeprefix("sha256:")[:20]
         build_id = f"build_{short_digest}"
         final_dir = self.workspace.resolve(Path("dist") / draft.metadata.id / build_id)
@@ -78,15 +139,29 @@ class AgentBundleBuilder:
         )
         bundle_root = staging / "agent-bundle"
         bundle_root.mkdir(parents=True, exist_ok=False)
+        resource_reference = None
         try:
             self._copy_runtime_source(bundle_root, draft)
             self._write_runtime_launch_config(bundle_root, draft)
+            if resource_build is not None:
+                resource_reference = resource_build.materialize(
+                    bundle_root / "platform-resources"
+                )
+                if resource_reference.snapshot_digest != resource_build.snapshot.digest:
+                    raise ValueError("Resource Build reference does not match admitted snapshot")
             launch_config = bundle_root / "runtime" / "agentengine.yaml"
             hosted_kernel_requirement = build_hosted_kernel_requirement(
                 runtime_type=runtime_type,
                 entry_point=runtime_lock.get("entryPoint"),
                 agent_variable=runtime_lock.get("agentVariable"),
                 launch_config=launch_config.read_bytes() if launch_config.is_file() else None,
+                composition_profile_digest=composition_profile_digest_value,
+                plugin_lock_digest=plugin_lock_digest_value,
+                provider_ref=(
+                    composition_profile.agent_provider.ref
+                    if composition_profile is not None
+                    else None
+                ),
             )
             hosted_kernel_requirement_digest_value = hosted_kernel_requirement_digest(
                 hosted_kernel_requirement
@@ -98,13 +173,40 @@ class AgentBundleBuilder:
                 runtime_lock=runtime_lock,
                 resolved_digest=resolved_digest,
                 plugin_lock=plugin_lock,
+                composition_profile=composition_profile,
+                composition_profile_digest_value=composition_profile_digest_value,
                 hosted_kernel_requirement=hosted_kernel_requirement,
                 hosted_kernel_requirement_digest_value=hosted_kernel_requirement_digest_value,
+                compatibility_facts_digest_value=compatibility_facts_digest_value,
+                resource_build_digest=(
+                    resource_reference.digest if resource_reference is not None else None
+                ),
+                resource_snapshot_digest=(
+                    resource_reference.snapshot_digest
+                    if resource_reference is not None
+                    else None
+                ),
+            )
+            self._write_json(
+                bundle_root / "compatibility-report.json",
+                build_bundle_compatibility_report(
+                    draft=draft,
+                    composition=composition,
+                    runtime_lock=runtime_lock,
+                    resolved_digest=resolved_digest,
+                    facts_digest=compatibility_facts_digest_value,
+                    plugin_lock_digest=plugin_lock_digest_value,
+                    composition_profile_digest=composition_profile_digest_value,
+                ),
             )
             self._write_json(
                 bundle_root / "hosted-kernel-requirements.json",
                 hosted_kernel_requirement,
             )
+            # Secrets are references at every declarative boundary.  Scan the
+            # final materialized Bundle before its file manifest/digest are
+            # sealed, so an accidental literal cannot become a deployable ZIP.
+            assert_bundle_security(bundle_root)
             # The manifest is a complete content declaration. Write this
             # auxiliary checksum file first, then include it in the manifest
             # entries; otherwise a Server-side full-membership check correctly
@@ -118,12 +220,29 @@ class AgentBundleBuilder:
                 resolved_digest=resolved_digest,
                 runtime_type=runtime_type,
                 source_digest=source_digest,
-                plugin_lock_digest=plugin_lock_digest,
+                plugin_lock_digest=plugin_lock_digest_value,
+                composition_mode="composed" if composition is not None else "legacy",
+                composition_profile_digest=composition_profile_digest_value,
                 hosted_kernel_requirement_digest=hosted_kernel_requirement_digest_value,
+                resource_build_digest=(
+                    resource_reference.digest if resource_reference is not None else None
+                ),
+                resource_snapshot_digest=(
+                    resource_reference.snapshot_digest
+                    if resource_reference is not None
+                    else None
+                ),
                 files=files,
             )
             manifest.bundle_digest = compute_bundle_digest(manifest)
-            self._write_json(bundle_root / "manifest.json", manifest.model_dump(by_alias=True))
+            # Keep the on-disk manifest on the same ``exclude_none`` wire
+            # projection used by ``compute_bundle_digest``.  New v2 archives
+            # always state whether they select legacy or composed execution;
+            # only historical archives may omit that discriminator.
+            self._write_json(
+                bundle_root / "manifest.json",
+                manifest.model_dump(by_alias=True, exclude_none=True),
+            )
             archive = staging / "agent-bundle.zip"
             self._write_zip(bundle_root, archive)
             final_dir.parent.mkdir(parents=True, exist_ok=True)
@@ -144,6 +263,8 @@ class AgentBundleBuilder:
             source_digest=source_digest,
             runtime_lock=runtime_lock,
             bundle_digest=manifest.bundle_digest,
+            resource_build_digest=manifest.resource_build_digest,
+            resource_snapshot_digest=manifest.resource_snapshot_digest,
             artifact_path=self.workspace.relative(zip_path),
             created_at=now,
             completed_at=now,
@@ -166,8 +287,13 @@ class AgentBundleBuilder:
         runtime_lock: dict,
         resolved_digest: str,
         plugin_lock: dict,
+        composition_profile: CompositionProfile | None,
+        composition_profile_digest_value: str | None,
         hosted_kernel_requirement: dict,
         hosted_kernel_requirement_digest_value: str,
+        compatibility_facts_digest_value: str,
+        resource_build_digest: str | None,
+        resource_snapshot_digest: str | None,
     ) -> None:
         definition_digest = compiled.resolved.resolved_digest
         resolved_payload = compiled.resolved.model_dump(
@@ -186,14 +312,30 @@ class AgentBundleBuilder:
         self._write_json(root / "agentkit.lock", dependency_lock)
         self._write_json(root / "runtime-lock.json", runtime_lock)
         self._write_json(root / "plugin-lock.json", plugin_lock)
+        if composition_profile is not None:
+            # A resolved profile is an immutable composition input, not a
+            # second editable Agent spec.  It is only written once its
+            # deterministic lock has already been resolved by PluginRegistry.
+            self._write_json(
+                root / "composition-profile.json",
+                composition_profile.model_dump(
+                    by_alias=True,
+                    exclude_none=True,
+                    mode="json",
+                ),
+            )
         instructions = root / "instructions"
         instructions.mkdir()
         (instructions / "system.md").write_text(
-            draft.spec.instructions.system.rstrip() + "\n", encoding="utf-8"
+            compiled.resolved.instructions.system.rstrip() + "\n", encoding="utf-8"
         )
         (instructions / "task.md").write_text(
-            draft.spec.instructions.task.rstrip() + "\n", encoding="utf-8"
+            compiled.resolved.instructions.task.rstrip() + "\n", encoding="utf-8"
         )
+        if compiled.resolved.soul is not None:
+            (instructions / "soul.md").write_text(
+                render_soul_markdown(compiled.resolved.soul), encoding="utf-8"
+            )
         for skill in compiled.resolved.capabilities.skills:
             source = self.workspace.resolve(
                 Path("capabilities/skills") / skill["name"],
@@ -238,25 +380,39 @@ class AgentBundleBuilder:
                 "components": components,
             },
         )
-        self._write_json(
-            root / "provenance.json",
-            {
-                "format": "agentkit.provenance/v1",
-                "agentId": draft.metadata.id,
-                "sourceRevision": draft.metadata.revision,
-                "sourceDigest": compiled.resolved.source_digest,
-                "definitionDigest": definition_digest,
-                "resolvedDigest": resolved_digest,
-                "compilerVersion": compiled.resolved.compiler_version,
-                "runtimeContract": "agentkit.runtime/v1",
-                "hostedKernel": {
-                    "requirementsPath": "hosted-kernel-requirements.json",
-                    "requirementDigest": hosted_kernel_requirement_digest_value,
-                    "contractSet": hosted_kernel_requirement["kernelContract"]["set"],
-                    "contractDigest": hosted_kernel_requirement["kernelContract"]["digest"],
-                },
+        provenance = {
+            "format": "agentkit.provenance/v1",
+            "agentId": draft.metadata.id,
+            "sourceRevision": draft.metadata.revision,
+            "sourceDigest": compiled.resolved.source_digest,
+            "definitionDigest": definition_digest,
+            "resolvedDigest": resolved_digest,
+            "compilerVersion": compiled.resolved.compiler_version,
+            "runtimeContract": "agentkit.runtime/v1",
+            "compatibility": {
+                "reportPath": "compatibility-report.json",
+                "factsDigest": compatibility_facts_digest_value,
             },
-        )
+            "hostedKernel": {
+                "requirementsPath": "hosted-kernel-requirements.json",
+                "requirementDigest": hosted_kernel_requirement_digest_value,
+                "contractSet": hosted_kernel_requirement["kernelContract"]["set"],
+                "contractDigest": hosted_kernel_requirement["kernelContract"]["digest"],
+            },
+        }
+        if composition_profile is not None:
+            provenance["composition"] = {
+                "profilePath": "composition-profile.json",
+                "profileDigest": composition_profile_digest_value,
+                "pluginLockDigest": sha256_digest(canonical_json(plugin_lock)),
+            }
+        if resource_build_digest is not None and resource_snapshot_digest is not None:
+            provenance["platformResources"] = {
+                "manifestPath": "platform-resources/resource-build.json",
+                "resourceBuildDigest": resource_build_digest,
+                "resourceSnapshotDigest": resource_snapshot_digest,
+            }
+        self._write_json(root / "provenance.json", provenance)
 
     def _runtime_snapshot(self, draft: AgentDraft, compiled) -> tuple[str, str, dict]:
         runtime = draft.spec.runtime
@@ -269,9 +425,7 @@ class AgentBundleBuilder:
                 content = path.read_bytes()
                 relative = path.relative_to(source_root).as_posix()
                 digest = f"sha256:{hashlib.sha256(content).hexdigest()}"
-                source_files.append(
-                    {"path": relative, "sha256": digest, "size": len(content)}
-                )
+                source_files.append({"path": relative, "sha256": digest, "size": len(content)})
             source_digest = sha256_digest(canonical_json(source_files))
         bound_models = [
             item.model for item in self.compiler.catalog.resolve_models(draft.spec.bindings)
@@ -290,9 +444,11 @@ class AgentBundleBuilder:
             "model": compiled.resolved.model.model,
             "models": list(dict.fromkeys(bound_models)),
         }
-        return runtime_type, source_digest, {
-            key: value for key, value in lock.items() if value is not None
-        }
+        return (
+            runtime_type,
+            source_digest,
+            {key: value for key, value in lock.items() if value is not None},
+        )
 
     def _copy_runtime_source(self, bundle_root: Path, draft: AgentDraft) -> None:
         runtime = draft.spec.runtime