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

ksadk/studio/builder.py

@@ -3,13 +3,21 @@
 from __future__ import annotations
 
 import hashlib
+import logging
 import shutil
 import zipfile
 from datetime import datetime, timezone
 from pathlib import Path
 from uuid import uuid4
 
-from ksadk.studio.capabilities import canonical_json, sha256_digest
+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,
@@ -18,11 +26,18 @@ from ksadk.studio.contracts import (
     BundleManifest,
     FileEntry,
 )
+from ksadk.studio.hosted_kernel import (
+    build_hosted_kernel_requirement,
+    hosted_kernel_requirement_digest,
+)
 from ksadk.studio.repository import BuildRepository
+from ksadk.studio.soul import render_soul_markdown
 from ksadk.studio.workspace import Workspace
 
 _ZIP_TIMESTAMP = (1980, 1, 1, 0, 0, 0)
 
+LOGGER = logging.getLogger(__name__)
+
 
 class AgentBundleBuilder:
     def __init__(
@@ -36,18 +51,46 @@ 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,
+    ) -> BuildRecord:
+        LOGGER.info(
+            "bundle build started: agent=%s revision=%s",
+            draft.metadata.id,
+            draft.metadata.revision,
+        )
         compiled = self.compiler.compile(draft)
+        # 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)
-        resolved_digest = sha256_digest(
-            canonical_json(
-                {
-                    "definitionDigest": compiled.resolved.resolved_digest,
-                    "runtime": runtime_lock,
-                    "sourceDigest": source_digest,
-                }
-            )
+        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
+        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)
@@ -61,32 +104,79 @@ class AgentBundleBuilder:
         bundle_root = staging / "agent-bundle"
         bundle_root.mkdir(parents=True, exist_ok=False)
         try:
+            self._copy_runtime_source(bundle_root, draft)
+            self._write_runtime_launch_config(bundle_root, draft)
+            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,
+            )
+            hosted_kernel_requirement_digest_value = hosted_kernel_requirement_digest(
+                hosted_kernel_requirement
+            )
             self._write_payload(
                 bundle_root,
                 draft,
                 compiled,
                 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,
             )
-            self._copy_runtime_source(bundle_root, draft)
+            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
+            # rejects the archive as self-inconsistent.
+            self._write_checksums(bundle_root)
             files = self._file_entries(bundle_root)
             manifest = BundleManifest(
+                bundle_format="agentkit.bundle/v2",
                 agent_id=draft.metadata.id,
                 source_revision=draft.metadata.revision,
                 resolved_digest=resolved_digest,
                 runtime_type=runtime_type,
                 source_digest=source_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,
                 files=files,
             )
-            digest_payload = manifest.model_dump(
-                by_alias=True,
-                exclude={"bundle_digest"},
-                exclude_none=True,
-                mode="json",
+            manifest.bundle_digest = compute_bundle_digest(manifest)
+            # 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),
             )
-            manifest.bundle_digest = sha256_digest(canonical_json(digest_payload))
-            self._write_json(bundle_root / "manifest.json", manifest.model_dump(by_alias=True))
-            self._write_checksums(bundle_root)
             archive = staging / "agent-bundle.zip"
             self._write_zip(bundle_root, archive)
             final_dir.parent.mkdir(parents=True, exist_ok=True)
@@ -111,7 +201,14 @@ class AgentBundleBuilder:
             created_at=now,
             completed_at=now,
         )
-        return self.repository.save(record)
+        saved = self.repository.save(record)
+        LOGGER.info(
+            "bundle build finished: agent=%s build=%s artifact=%s",
+            draft.metadata.id,
+            saved.id,
+            saved.artifact_path,
+        )
+        return saved
 
     def _write_payload(
         self,
@@ -121,6 +218,12 @@ 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,
     ) -> None:
         definition_digest = compiled.resolved.resolved_digest
         resolved_payload = compiled.resolved.model_dump(
@@ -138,14 +241,31 @@ 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"],
@@ -190,19 +310,33 @@ 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",
+        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)),
+            }
+        self._write_json(root / "provenance.json", provenance)
 
     def _runtime_snapshot(self, draft: AgentDraft, compiled) -> tuple[str, str, dict]:
         runtime = draft.spec.runtime
@@ -215,9 +349,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)
@@ -236,9 +368,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
@@ -252,6 +386,29 @@ class AgentBundleBuilder:
             target.parent.mkdir(parents=True, exist_ok=True)
             target.write_bytes(source.read_bytes())
 
+    def _write_runtime_launch_config(self, bundle_root: Path, draft: AgentDraft) -> None:
+        """Make the copied runtime source directly launchable by the profile image.
+
+        Production Code deployments execute the runtime directory through the
+        KsADK web command. The source snapshot therefore needs an explicit,
+        immutable framework declaration rather than relying on heuristics or a
+        user-supplied YAML that could disagree with the admitted runtime lock.
+        """
+
+        runtime = draft.spec.runtime
+        if runtime is None or not runtime.project_path:
+            return
+        self._write_json(
+            bundle_root / "runtime" / "agentengine.yaml",
+            {
+                "name": draft.metadata.id,
+                "framework": runtime.type,
+                "entry_point": runtime.entry_point or "agent.py",
+                "agent_variable": runtime.agent_variable or "root_agent",
+                "package": ".",
+            },
+        )
+
     @staticmethod
     def _source_files(root: Path) -> list[Path]:
         files: list[Path] = []

ksadk/studio/capabilities.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from typing import Any, Protocol, cast
 
 from ksadk.studio.contracts import (
+    BundleManifest,
     CapabilityRef,
     MCPServerRef,
     ModelSpec,
@@ -35,6 +36,22 @@ def sha256_digest(payload: bytes) -> str:
     return f"sha256:{hashlib.sha256(payload).hexdigest()}"
 
 
+def compute_bundle_digest(manifest: BundleManifest) -> str:
+    """重算 BundleManifest 的 bundle_digest。
+
+    必须与 AgentBundleBuilder 产出时逐字一致：对去掉 bundle_digest 字段后的
+    canonical JSON 求 sha256。Runtime 加载 bundle 时据此校验 manifest 自身
+    未被篡改，避免 builder 与 runtime 各持一份易漂移的计算逻辑。
+    """
+    payload = manifest.model_dump(
+        by_alias=True,
+        exclude={"bundle_digest"},
+        exclude_none=True,
+        mode="json",
+    )
+    return sha256_digest(canonical_json(payload))
+
+
 def require_exact_version(version: str, *, field: str) -> None:
     if not _EXACT_SEMVER.fullmatch(version):
         raise StudioError(