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

ksadk/studio/attachment_store.py

@@ -0,0 +1,187 @@
+"""Bounded, content-addressed local attachments for ConversationInput."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from ksadk.studio.errors import StudioError, not_found
+from ksadk.studio.workspace import Workspace
+
+_ATTACHMENT_REF = re.compile(r"^attachment://sha256/(?P<digest>[0-9a-f]{64})$")
+_SAFE_FILENAME = re.compile(r"[^A-Za-z0-9._-]+")
+_TEXT_MEDIA_TYPES = {
+    "application/json",
+    "application/toml",
+    "application/xml",
+    "application/x-httpd-php",
+    "application/x-sh",
+    "application/x-yaml",
+}
+_TEXT_SUFFIXES = {
+    ".csv",
+    ".css",
+    ".go",
+    ".html",
+    ".ini",
+    ".java",
+    ".js",
+    ".json",
+    ".jsx",
+    ".log",
+    ".md",
+    ".py",
+    ".rs",
+    ".sh",
+    ".toml",
+    ".ts",
+    ".tsx",
+    ".txt",
+    ".xml",
+    ".yaml",
+    ".yml",
+}
+
+
+@dataclass(frozen=True)
+class StoredConversationAttachment:
+    attachment_ref: str
+    path: Path
+    name: str
+    media_type: str
+    size: int
+    digest: str
+
+
+class ConversationAttachmentStore:
+    """Persist only the small image/text inputs supported by local Studio."""
+
+    MAX_BYTES = 1_500_000
+
+    def __init__(self, workspace: Workspace) -> None:
+        self.workspace = workspace
+        self.root = self.workspace.resolve(".agentkit/assets/conversation-attachments")
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def store(self, content: bytes, *, filename: str, media_type: str) -> dict[str, object]:
+        if not content:
+            raise StudioError(
+                "CONVERSATION_ATTACHMENT_EMPTY",
+                "会话附件不能为空",
+                status_code=422,
+                field="file",
+            )
+        if len(content) > self.MAX_BYTES:
+            raise StudioError(
+                "CONVERSATION_ATTACHMENT_TOO_LARGE",
+                "会话附件不能超过 1.5 MiB",
+                status_code=413,
+                field="file",
+                details={"maxBytes": self.MAX_BYTES},
+            )
+        normalized_type = media_type.split(";", 1)[0].strip().lower()
+        safe_name = _SAFE_FILENAME.sub("-", Path(filename).name).strip(".-")[:160]
+        safe_name = safe_name or "attachment"
+        if not self._supported(content, filename=safe_name, media_type=normalized_type):
+            raise StudioError(
+                "CONVERSATION_ATTACHMENT_TYPE_UNSUPPORTED",
+                "会话附件仅支持图片或 UTF-8 文本、代码文件",
+                status_code=415,
+                field="file",
+            )
+
+        digest = hashlib.sha256(content).hexdigest()
+        content_path = self.root / f"{digest}.bin"
+        metadata_path = self.root / f"{digest}.json"
+        if not content_path.is_file():
+            self.workspace.atomic_write_bytes(content_path, content)
+        if not metadata_path.is_file():
+            self.workspace.atomic_write_text(
+                metadata_path,
+                json.dumps(
+                    {
+                        "digest": digest,
+                        "name": safe_name,
+                        "mediaType": normalized_type or "application/octet-stream",
+                        "size": len(content),
+                    },
+                    ensure_ascii=False,
+                    sort_keys=True,
+                    separators=(",", ":"),
+                )
+                + "\n",
+            )
+        # The reference identifies content, so its persisted metadata is the
+        # authority as well.  Returning a second upload's conflicting name or
+        # media type would create a ref that immediately fails on resolution.
+        stored = self.resolve(f"attachment://sha256/{digest}")
+        return {
+            "attachmentRef": stored.attachment_ref,
+            "name": stored.name,
+            "mediaType": stored.media_type,
+            "size": stored.size,
+            "digest": stored.digest,
+        }
+
+    def resolve(self, attachment_ref: str) -> StoredConversationAttachment:
+        match = _ATTACHMENT_REF.fullmatch(attachment_ref)
+        if match is None:
+            raise not_found("conversation-attachment", attachment_ref)
+        digest = match.group("digest")
+        content_path = self.root / f"{digest}.bin"
+        metadata_path = self.root / f"{digest}.json"
+        if not content_path.is_file() or not metadata_path.is_file():
+            raise not_found("conversation-attachment", attachment_ref)
+        try:
+            metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+            content = content_path.read_bytes()
+            content_size = len(content)
+        except (OSError, json.JSONDecodeError) as exc:
+            raise StudioError(
+                "CONVERSATION_ATTACHMENT_CORRUPT",
+                "会话附件元数据损坏",
+                status_code=409,
+                details={"attachmentRef": attachment_ref},
+            ) from exc
+        actual_digest = hashlib.sha256(content).hexdigest()
+        if (
+            metadata.get("digest") != digest
+            or actual_digest != digest
+            or int(metadata.get("size") or -1) != content_size
+        ):
+            raise StudioError(
+                "CONVERSATION_ATTACHMENT_CORRUPT",
+                "会话附件完整性校验失败",
+                status_code=409,
+                details={"attachmentRef": attachment_ref},
+            )
+        return StoredConversationAttachment(
+            attachment_ref=attachment_ref,
+            path=content_path,
+            name=str(metadata.get("name") or "attachment"),
+            media_type=str(metadata.get("mediaType") or "application/octet-stream"),
+            size=content_size,
+            digest=digest,
+        )
+
+    @staticmethod
+    def _supported(content: bytes, *, filename: str, media_type: str) -> bool:
+        if media_type.startswith("image/"):
+            return True
+        if (
+            media_type.startswith("text/")
+            or media_type in _TEXT_MEDIA_TYPES
+            or Path(filename).suffix.lower() in _TEXT_SUFFIXES
+        ):
+            try:
+                content.decode("utf-8")
+            except UnicodeDecodeError:
+                return False
+            return True
+        return False
+
+
+__all__ = ["ConversationAttachmentStore", "StoredConversationAttachment"]

ksadk/studio/authoring.py

@@ -694,6 +694,16 @@ class AgentAuthoringService:
         ignored.add(".git")
         entries: list[dict[str, Any]] = []
         for path in sorted(root.rglob("*"), key=lambda item: item.as_posix()):
+            relative = path.relative_to(root).as_posix()
+            # Studio state and VCS internals may legitimately contain symlinks
+            # (for example managed Node dependencies). They are outside the
+            # imported project contract, so prune them before applying the
+            # source-tree symlink safety check.
+            if any(
+                relative == ignored_dir or relative.startswith(ignored_dir + "/")
+                for ignored_dir in (".agentkit", ".git")
+            ):
+                continue
             if path.is_symlink():
                 raise StudioError(
                     "AUTHORING_SOURCE_UNSAFE",
@@ -703,10 +713,6 @@ class AgentAuthoringService:
                 )
             if not path.is_file() or path.name in ignored:
                 continue
-            # 跳过 .agentkit / .git 目录下的文件
-            relative = path.relative_to(root).as_posix()
-            if any(relative.startswith(ignored_dir + "/") for ignored_dir in (".agentkit", ".git")):
-                continue
             content = path.read_bytes()
             entries.append(
                 {

ksadk/studio/authoring_coordinator.py

@@ -278,7 +278,6 @@ class StudioAuthoringCoordinator:
             resolved = (spec or default_agent_spec(template, description=description)).model_copy(
                 deep=True
             )
-            canonical_runtime = self.backend.runtime_ref(agent_id, runtime_type)
             proposed_runtime = resolved.runtime
             if proposed_runtime is not None and proposed_runtime.type != runtime_type:
                 raise StudioError(
@@ -291,7 +290,18 @@ class StudioAuthoringCoordinator:
                         "specRuntimeType": proposed_runtime.type,
                     },
                 )
-            if proposed_runtime is not None:
+            if runtime_type == "plugin":
+                if proposed_runtime is None or proposed_runtime.provider_ref is None:
+                    raise StudioError(
+                        "AGENT_PROVIDER_REFERENCE_REQUIRED",
+                        "外部 AgentProvider 必须选择一个已安装的精确版本",
+                        status_code=422,
+                        field="spec.runtime.providerRef",
+                    )
+                canonical_runtime = proposed_runtime.model_copy(deep=True)
+            else:
+                canonical_runtime = self.backend.runtime_ref(agent_id, runtime_type)
+            if proposed_runtime is not None and runtime_type != "plugin":
                 if runtime_type == "codex" and proposed_runtime.version:
                     canonical_runtime.version = proposed_runtime.version
                 elif runtime_type in {"adk", "langgraph"}:

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,
@@ -24,6 +31,7 @@ from ksadk.studio.hosted_kernel import (
     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)
@@ -43,29 +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 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))
+        # 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)
@@ -98,13 +123,32 @@ 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,
+            )
+            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 +162,21 @@ 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,
                 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)
@@ -166,8 +219,11 @@ 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(
@@ -186,14 +242,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 +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",
-                "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)),
+            }
+        self._write_json(root / "provenance.json", provenance)
 
     def _runtime_snapshot(self, draft: AgentDraft, compiled) -> tuple[str, str, dict]:
         runtime = draft.spec.runtime
@@ -269,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)
@@ -290,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

ksadk/studio/cloud.py

@@ -1151,6 +1151,7 @@ class DirectAgentEngineCloudDeploymentGateway:
         *,
         session_id: str,
         after_seq_id: int | None = None,
+        offset: int | None = None,
         limit: int = 200,
     ) -> dict[str, Any]:
         """Read canonical events, including public Interaction/v1 frames."""
@@ -1160,6 +1161,7 @@ class DirectAgentEngineCloudDeploymentGateway:
                 agent_id=self._chat_agent_id(deployment),
                 session_id=session_id,
                 after_seq_id=after_seq_id,
+                offset=offset,
                 limit=limit,
             )
         except AgentEngineAPIError as exc:
@@ -1922,6 +1924,7 @@ class CloudDeploymentService:
         *,
         session_id: str,
         after_seq_id: int | None = None,
+        offset: int | None = None,
         limit: int = 200,
     ) -> dict[str, Any]:
         deployment = await self._chat_target(deployment_id)
@@ -1936,6 +1939,7 @@ class CloudDeploymentService:
             deployment,
             session_id=session_id,
             after_seq_id=after_seq_id,
+            offset=offset,
             limit=limit,
         )
 

ksadk/studio/codex_agent_service.py

@@ -377,9 +377,17 @@ class CodexAgentService:
     def detail(self, agent_id: str | None = None) -> dict:
         snapshot = self.studio.codex_manifests.load(agent_id)
         _mcp_bindings, unresolved_mcp = self._mcp_bindings(snapshot.manifest)
+        builds_view: list[dict] = []
+        for item in self._builds(snapshot.manifest.name):
+            view = self.build_view(item)
+            try:
+                view["isCurrent"] = self.studio.codex_builder.is_current(item)
+            except Exception:
+                view["isCurrent"] = True
+            builds_view.append(view)
         return {
             "draft": self._project(snapshot),
-            "builds": [self.build_view(item) for item in self._builds(snapshot.manifest.name)],
+            "builds": builds_view,
             "validation": {"valid": True, "level": "build", "diagnostics": []},
             "manifestSha256": snapshot.manifest_sha256,
             "sourcePath": self.studio.workspace.relative(snapshot.source_path),
@@ -505,6 +513,7 @@ class CodexAgentService:
                 system=manifest.prompt,
                 task=manifest.task_prompt or "",
             )
+            draft.spec.soul = manifest.soul
             draft.spec.bindings.model_profile_id = bindings[0]
             draft.spec.bindings.model_profile_ids = bindings[1]
             draft.spec.bindings.skills = skill_bindings
@@ -527,6 +536,7 @@ class CodexAgentService:
                     system=manifest.prompt,
                     task=manifest.task_prompt or "",
                 ),
+                soul=manifest.soul,
                 bindings=AgentBindings(
                     model_profile_id=default_profile,
                     model_profile_ids=profiles,
@@ -576,6 +586,7 @@ class CodexAgentService:
             models=models if len(models) > 1 else None,
             prompt=prompt,
             task_prompt=task_prompt,
+            soul=spec.soul,
             skills=skill_ids or None,
             mcp_servers=mcp_servers or None,
             sandbox=spec.execution.sandbox,